Back to blog
X24LABS

Getting started with Stitch Agent (v1)

The original v1 setup guide: two CI jobs, a Docker image, and a handful of environment variables. Kept for historical reference.

Historical post. This guide describes Stitch v1, which ran inside your CI pipeline and distributed via a Docker image. If you are installing Stitch today, follow Getting started with Stitch 2.0 instead. The stitch-monitor / stitch-heal jobs and the ghcr.io/x24labs/stitch image are no longer maintained.

Setting up Stitch takes under five minutes. You add two jobs to your CI configuration and Stitch handles the rest. No servers, no API keys to manage, no dashboard to monitor.

Prerequisites

GitLab CI setup

Add these two jobs to your .gitlab-ci.yml:

stitch-monitor:
  stage: .post
  image: ghcr.io/x24labs/stitch:latest
  script:
    - stitch monitor
  when: on_failure

stitch-heal:
  stage: .post
  image: ghcr.io/x24labs/stitch:latest
  script:
    - stitch heal
  needs: ["stitch-monitor"]
  when: on_failure

The stitch-monitor job activates when any upstream job fails. It reads the logs and identifies the failure. The stitch-heal job takes the diagnosis and generates a fix.

Both jobs use the .post stage, so they run after all your regular pipeline stages. They only trigger on_failure, meaning they cost zero compute time when your pipeline passes.

GitHub Actions setup

Add a workflow file at .github/workflows/stitch.yml:

name: Stitch
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  heal:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/x24labs/stitch:latest
    steps:
      - uses: actions/checkout@v4
      - run: stitch monitor && stitch heal

This workflow triggers when your CI workflow fails. It checks out the code, runs the monitor, and applies the fix.

What happens next

When your pipeline fails:

  1. Stitch reads the failure logs
  2. It identifies the error type and affected files
  3. It generates a targeted patch
  4. It validates the fix by re-running the failing checks
  5. If the fix passes, it pushes a commit to a fix branch and opens a merge request

You review the MR like any other code change. By default, auto-merge is off. You decide when the fix lands.

Configuration

Stitch works with zero configuration. For teams that want more control, you can set options via environment variables:

Verifying the setup

Push a commit that intentionally breaks a lint rule or test. Watch the pipeline fail, then watch Stitch pick it up. You should see a new branch and merge request within a few minutes.

If something is not working, check the Stitch job logs. They contain the full diagnosis and any errors encountered during the fix attempt.

Next steps

Back to blog