GitLab CI to verified AI code merges: complete 2026 workflow

A GitLab pipeline that goes red on an AI-generated patch tells you nothing about why. Half the time it's a real regression; the other half it's a flaky runner, a stale cache, or a dependency that timed out. Wire a verification stage into GitLab CI and every merge request gets a receipt that separates the two instead of leaving you to re-run the pipeline and hope.

Why this matters

AI coding agents produce patches fast enough that manual triage of every red pipeline stops scaling around the third or fourth agent-generated MR of the day. A test suite that fails because a package registry timed out looks identical, in the GitLab pipeline view, to a test suite that fails because the agent broke a real contract. Both show a red X. Only one of them means the code is wrong.

That ambiguity is expensive in exactly the workflows AI agents are supposed to speed up. A reviewer who can't trust the pipeline opens the logs on every failure, which erases most of the time saved by having an agent write the patch. Running the patch through an isolated sandbox before it reaches a human reviewer, and getting a readable verdict back, removes that step. AdaptOrch runs the code before and after the patch in the sandbox and reports what actually changed, not just whether the exit code was zero.

This guide covers the 2026 setup: one new stage, one job, three settings you have to get right.

Before you start

• Maintainer or Owner role on the GitLab project — you need it to edit .gitlab-ci.yml and add CI/CD variables under Settings > CI/CD > Variables.
• An AdaptOrch API key and a GitLab Runner with a Docker executor (shared runners work; self-hosted is fine too) that can pull the sandbox image and reach your package registry.
• The gotcha that bites at step 4: a CI/CD variable marked Protect variable is only injected into pipelines running on protected branches. Merge request pipelines run on the source branch, which is usually unprotected — so the key is simply absent at job time and the job fails on auth, not on the code. Decide this before you write the job, not after the third red run.

Set up the verification stage

1. Go to Settings > CI/CD > Variables and click Add variable.
2. Set Key to ADAPTORCH_API_KEY, paste the key into Value, toggle Mask variable on, and leave Protect variable off unless every branch you verify is protected.
3. Open .gitlab-ci.yml and add a new entry to your existing stages: list — verify, placed after test.
4. Commit to your default branch.

Expected result: the CI/CD > Variables page lists ADAPTORCH_API_KEY as masked, and the next pipeline graph shows an empty verify stage with no jobs in it yet.

Configure the sandbox job

1. Under verify, add a job named adaptorch-verify.
2. Set image: to a Docker image carrying your project's runtime plus the AdaptOrch CLI. A slim base image with the CLI installed in before_script works if you don't maintain a custom image.
3. In script:, invoke the AdaptOrch CLI with $ADAPTORCH_API_KEY in the environment and pass $CI_MERGE_REQUEST_DIFF_BASE_SHA and $CI_COMMIT_SHA so the sandbox knows exactly which diff it is verifying.
4. Add artifacts: with a paths: entry pointing at the receipt file so it downloads straight from the pipeline view.
5. Set allow_failure: true for the first week. Flip it to false once you trust the verdicts.

Expected result: pushing a commit to a merge request triggers adaptorch-verify, the runner pulls the image, the patch executes in an isolated sandbox, and the Job artifacts panel shows a downloadable receipt when the job ends.

If you're still choosing an isolation approach, the rundown of sandbox tools for testing AI-generated code covers the tradeoffs between hosted and self-run sandboxes.

Wire it into merge request pipelines

1. Add a rules: block to adaptorch-verify scoped to if: '$CI_PIPELINE_SOURCE == "merge_request_event"' so it fires on MR pipelines only, not on every push to a feature branch.
2. Add needs: [] if you want the sandbox job to start immediately instead of queuing behind the full test stage. Sandbox runs are typically the long pole; starting them first shortens wall-clock time on the whole pipeline.
3. In Settings > Merge requests, enable Pipelines must succeed.

Expected result: opening or updating a merge request starts adaptorch-verify in parallel with your normal test jobs, and the Merge button stays disabled until the stage passes — provided you already set allow_failure: false.

One rule worth writing on the wall: a red pipeline is a question, not an answer. The receipt is what turns it into an answer.

Variant: verify on every push to main

Some teams want a second check after merge, especially when an agent auto-merges small patches through a bot account. Duplicate the job under a new name, swap the rules: condition to if: '$CI_COMMIT_BRANCH == "main"', and drop the merge_request_event scoping.

This produces a second receipt confirming the merged state behaves like the verified diff. It catches the narrow case where conflict resolution during merge introduces something the original patch never contained — rare, but invisible to pre-merge verification by definition.

Expected result: two receipts per change in 2026 — one on the MR, one on main — with matching verdicts when nothing was altered at merge time.

Reading the receipt

The output separates a failing assertion in the patched code from a job that died because a registry was unreachable or a container hit its memory ceiling. AdaptOrch reports the difference in words rather than a numeric score, and it does not claim the patch is correct — only what the evidence from the before-and-after runs shows.

That distinction is the whole point of the stage. A receipt saying "dependency install failed, no code signal" means re-run the job. A receipt naming a test that passed before the patch and fails after it means read the diff.

If agent-generated patches in your repo already fail for reasons unrelated to the code, the guide on how to automatically flag environment failures covers the same split outside the GitLab context.

Troubleshooting

• Job fails instantly with an auth error. ADAPTORCH_API_KEY is marked Protect variable while the MR pipeline runs on an unprotected source branch. Unprotect the variable or run verification on a protected branch.
• Sandbox job hits the timeout. GitLab's project-wide job timeout defaults to 1 hour. Raise it in Settings > CI/CD > General pipelines if your patches touch large dependency trees.
• Two receipts for one commit. A branch pipeline and an MR pipeline both ran. Tighten the rules: block to a single CI_PIPELINE_SOURCE value.
• Every run reports an environment failure. The runner has no egress to your package registry. A locked-down runner misreports real bugs as environment noise because the sandbox never gets far enough to test the code.
• Merge button stays enabled after a failing verdict. allow_failure: false and Pipelines must succeed have to be set together. Either one alone changes nothing.

Customize your workflow

Once the base stage is stable, narrow it. Run verification only on merge requests authored by your agent's bot account, or gate it on a label via $CI_MERGE_REQUEST_LABELS so human-authored MRs skip the sandbox — different risk profile, different treatment.

If GitLab isn't your only pipeline, the comparison of CI tools for AI-generated code verification maps how the same stage translates to other providers.

Platform teams rolling this out across dozens of repositories in 2026 should standardize the job as a shared CI template first — the platform engineers guide to AI code verification covers the org-wide version of this setup, including how to keep one template from breaking forty pipelines at once.

FAQ

One last thing

The most common broken GitLab setup in 2026 isn't the sandbox job — it's the Protect variable toggle quietly withholding the API key on unprotected source branches, which makes an auth failure look like a code failure on the very first run. Check that toggle before you debug anything else, and you'll skip the hour most teams lose here.

Related guides

• Tools to catch flaky tests vs real bugs
• Code review automation for technical leads