GitLab Integration

Code hosting, merge requests, and CI pipeline.

Prerequisites

  • A GitLab instance or group with API access
  • An Ironwork workspace with owner or admin role
  • For service accounts (recommended): separate GitLab users for Build and Review with appropriate project permissions

Setup

  1. Navigate to Integrations in your Ironwork dashboard.
  2. Click Connect on the GitLab card.
  3. Authorize the OAuth connection. Ironwork will request access to your GitLab repositories.
  4. Once connected, go to Projects and add repositories from your GitLab instance. Ironwork clones them for agent access.

Service accounts

Recommended setup

Create separate GitLab users for Build and Review, each with their own Personal Access Token (PAT). This is the recommended configuration for production use.

Using separate service accounts provides several benefits:

  • Audit trail — commits from Build and review comments from Review appear under their respective GitLab accounts, making it clear which changes are human-authored and which are agent-authored
  • Separate permissions — you can grant Build write access (to push commits) while giving Review read-only access plus comment permissions
  • Token rotation — rotate PATs independently without affecting the other agent

Configure PATs in your workspace's integration settings. Each PAT is encrypted at rest with AES-256-GCM.

What Ironwork accesses

  • Repository files — cloned for codebase analysis and code writing
  • Merge request diffs — the full diff of all changed files
  • MR discussions — all comments, threads, and inline notes
  • CI pipeline jobs — status, logs, and error output for each job
  • MR metadata — title, description, author, branches, version SHAs

Webhook events

Ironwork listens to GitLab webhook events to trigger agents and react to changes. Webhook payloads are verified using the configured webhook secret.

  • Merge request updates — when an MR is created, updated, or assigned to an agent
  • Note creation — when comments are posted on MRs (triggers agent responses to feedback)
  • Pipeline status changes — when CI jobs succeed or fail (Build fixes failures, Review factors results into scoring)

Troubleshooting

PAT expiration

GitLab Personal Access Tokens have expiration dates. When a PAT expires, the affected agent will fail to interact with GitLab. Ironwork includes a PAT refresher that monitors token health, but you may need to regenerate and re-enter the PAT in your integration settings.

Clone failures

If a project fails to clone, verify that the OAuth user or service account has access to the repository. Private repositories require explicit access. Check that the repository URL is correct and the GitLab instance is reachable from your Ironwork deployment.

Webhook delivery

GitLab webhooks require your Ironwork instance to be reachable at a public URL. Verify the webhook URL is correctly configured in your GitLab project settings. Check your deployment logs for webhook signature validation failures, which indicate a mismatched webhook secret.