GitLab Integration

Pilot integrates with GitLab to receive issues and create merge requests. It supports both GitLab.com and self-hosted GitLab instances.

Setup

1. Create a GitLab Token

1. Go to GitLab → Preferences → Access Tokens
2. Create a Personal Access Token or Project Access Token with scopes:
   • api — full API access
   • read_repository / write_repository — for git operations

2. Configure Pilot

# ~/.pilot/config.yaml
gitlab:
  enabled: true
  token: ${GITLAB_TOKEN}
  base_url: https://gitlab.com
  project: my-group/my-project
  pilot_label: pilot
  polling:
    enabled: true
    interval: 30s
    label: pilot

3. Create the pilot Label

In your GitLab project, go to Issues → Labels and create a pilot label.

Configuration Reference

Polling Mode

When polling is enabled, Pilot periodically lists open issues with the pilot label, sorted by creation date (oldest first). Issues with pilot-in-progress or pilot-done labels are skipped.

Sequential Execution

By default, Pilot processes one issue at a time in sequential mode:

1. Find the oldest unprocessed issue with the pilot label
2. Execute the implementation
3. Create a merge request
4. Wait for the MR to be merged
5. Move to the next issue

If the MR has conflicts or times out, Pilot pauses for 5 minutes before retrying.

Webhook Mode

For real-time issue detection, configure a GitLab webhook:

1. Go to your project → Settings → Webhooks
2. Set the URL to https://your-pilot.example.com/webhooks/gitlab
3. Set the Secret token to match your webhook_secret config
4. Enable Issues events

Signature Validation

GitLab webhooks use a simple token comparison via the X-Gitlab-Token header. This differs from GitHub’s HMAC-SHA256 signature approach.

gitlab:
  webhook_secret: ${GITLAB_WEBHOOK_SECRET}

If webhook_secret is empty, all incoming webhooks are accepted (development mode only).

Supported Events

Merge Request Management

When Pilot completes work on an issue, it creates a merge request in your GitLab project.

MR Options

Merge Waiting

In sequential mode, Pilot waits for the MR to be merged before processing the next issue. It polls MR status every 30 seconds with a 1-hour timeout.

CI Status Tracking

Pilot monitors GitLab pipeline status on merge requests:

Stale Label Cleanup

Pilot automatically removes orphaned pilot-in-progress labels from issues that are no longer being actively processed. This prevents issues from getting stuck if Pilot restarts during execution.

The cleaner runs every 30 minutes (configurable) and removes the label if:

• No active Pilot execution exists for the issue
• The label was last updated more than 1 hour ago (configurable)

A comment is posted to the issue explaining the cleanup.

Labels

Differences from GitHub