GitLab CI/CD: Pipelines with Claude Code

A GitLab Runner is an agent that executes pipeline jobs. Set up via:

1. Register a runner:

1gitlab-runner register      --url https://gitlab.com/      --registration-token YOUR_TOKEN      --executor docker      --docker-image ubuntu:22.04

2. Docker executor (recommended for Claude Code): - Runs each job in a fresh container. - Isolation: no side effects between jobs. - Caching: GitLab can cache dependencies (node_modules, pip cache).

3. Define in .gitlab-ci.yml:

1stages:2     - review3     - build4     - deploy5 6   claude-review:7     stage: review8     image: ubuntu:22.049     script:10       - apt-get update && apt-get install -y git curl11       - npm install -g claude-code12       - claude-code run "Review this MR for security issues"13     only:14       - merge_requests

GitLab-hosted runners are free for public repos; private repos get 400 CI minutes/month free. Self-hosted runners run on your infrastructure (VMs, Kubernetes, your laptop even).

Merge requests (MRs) are GitLab's term for pull requests. When an MR is opened, GitLab automatically runs pipelines. Use this to invoke Claude Code:

1review-mr:2  stage: review3  script:4    - git fetch origin merge-requests/$CI_MERGE_REQUEST_IID/head:review-branch5    - git checkout review-branch6    - git diff origin/main...HEAD > /tmp/diff.txt7    - claude-code run "Review this MR diff for bugs and security issues"8  only:9    - merge_requests10  allow_failure: true  # Don't block MR if review fails

GitLab provides CI/CD variables like: - $CI_MERGE_REQUEST_IID = MR number. - $CI_MERGE_REQUEST_TITLE = MR title. - $CI_MERGE_REQUEST_DESCRIPTION = MR description. - $CI_COMMIT_SHA = commit hash.

Use these to provide context to Claude. After review, Claude posts findings as comments on the MR (via GitLab API) or as a note in the merge request discussion thread.

GitLab pipelines have stages. Jobs in the same stage run in parallel; subsequent stages wait for the previous stage to succeed.

Example pipeline:

1stages:2  - lint3  - test4  - review5  - build6  - deploy7 8lint:9  stage: lint10  script: npm run lint11  allow_failure: false  # Blocks pipeline if lint fails12 13test:14  stage: test15  script: npm test16  allow_failure: false17 18claude-review:19  stage: review  # Runs after test passes20  script:21    - npm install -g claude-code22    - claude-code run "Review code quality"23  allow_failure: true  # Doesn't block deploy24 25build:26  stage: build27  script: npm run build28 29deploy:30  stage: deploy31  script: npm run deploy32  only:33    - main  # Only deploy on main branch

Flow: Lint → Test → Review (in parallel or after test) → Build → Deploy. If test fails, review and build are skipped.

Artifacts are files saved from a job that can be downloaded or used by subsequent jobs.

1claude-analyze:2  stage: review3  script:4    - claude-code run "Analyze codebase" > analysis.json5  artifacts:6    paths:7      - analysis.json8    expire_in: 30 days9    reports:10      codequality: analysis.json  # GitLab parses as code quality report

GitLab recognizes certain report formats: - sast (SAST findings, mapped to GitLab UI) - dast (DAST findings) - codequality (code quality issues) - dependency_scanning (dependency vulnerabilities)

If you output JSON in the codequality format, GitLab displays findings in the MR UI automatically.

Make certain pipeline jobs required for merge. In GitLab project settings (Settings > Repository > Protected branches), set:

• Require Pipeline to Succeed: MR cannot be merged if any required job fails.
• Require Approval: Require specific users/teams to approve the MR.

Then in .gitlab-ci.yml, mark jobs as status checks:

1lint:2  stage: lint3  script: npm run lint4 5test:6  stage: test7  script: npm test8 9claude-security-review:10  stage: review11  script:12    - claude-code run "Check for security vulnerabilities"13  # This job must pass for MR to be mergeable14  allow_failure: false15  artifacts:16    reports:17      sast: security-report.json

If you set require pipeline success, the claude-security-review job must pass before merge. If Claude finds critical issues, the job fails, blocking merge until fixed.

Self-hosted runners run on your infrastructure. Advantages: - No concurrency limits. - Full OS access (install custom software). - Private network access.

Disadvantages: - You maintain the runner software and OS. - Security risk if not isolated properly.

Setup on a VM or Kubernetes:

1# Download and install GitLab Runner2curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | bash3sudo apt-get install gitlab-runner4 5# Register the runner6sudo gitlab-runner register   --url https://gitlab.com/   --registration-token YOUR_TOKEN   --executor docker   --tag-list "custom,docker"   --docker-image ubuntu:22.04

Then in your .gitlab-ci.yml, specify:

1claude-task:2  tags:3    - custom  # Run on self-hosted runner with 'custom' tag4  script:5    - claude-code run "Task here"

Best practices: - Use Docker executor for isolation. - Keep runner OS and runner software up to date. - Use separate runners for CI vs deploy (different permission levels). - Monitor runner health (CPU, memory, disk); alert if resources are low. - Rotate credentials regularly (registration tokens, API keys).

Scenario: Deploy a new feature, but first run it on 10% of traffic for 1 hour. If no errors, roll out 100%.

Pipeline:

1stages:2  - build3  - canary-deploy4  - canary-verify5  - full-deploy6 7build:8  stage: build9  script: npm run build10 11canary-deploy:12  stage: canary-deploy13  script:14    - kubectl set image deployment/app app=myrepo/app:$CI_COMMIT_SHA --record15    - kubectl patch deployment/app -p '{"spec": {"strategy": {"canary": {"weight": 10}}}}'16  environment:17    name: production18    deployment_tier: production19 20canary-verify:21  stage: canary-verify22  script:23    - sleep 300  # Wait 5 min for canary to serve traffic24    - claude-code run "Check if canary metrics (error rate, latency) are acceptable"25  allow_failure: false  # Block full deploy if canary fails26 27full-deploy:28  stage: full-deploy29  script:30    - kubectl set image deployment/app app=myrepo/app:$CI_COMMIT_SHA31    - kubectl rollout status deployment/app32  environment:33    name: production34  when: on_success  # Only run if canary-verify passes

Claude's role: After canary runs for 5 min, Claude checks metrics (error rate, latency, trace samples). If metrics look good, Claude gives a thumbs-up and full deploy proceeds. If metrics are bad, Claude reports the issue and blocks deploy.

Both GitLab CI/CD and GitHub Actions are excellent. Key differences:

| Feature | GitLab CI/CD | GitHub Actions | |---------|------------|-----------------| | Config file | .gitlab-ci.yml | .github/workflows/.yml | | Platform | GitLab (all-in-one) | GitHub (part of GitHub ecosystem) | | Pricing | Free for public + 400 min/mo private | Free for public + 2000 min/mo private | | Concurrency | Limited by plan | Limited by plan | | Marketplace | Less extensive | Large, well-documented | | Integration | Built into GitLab issues/MRs | Separate from PR UI | | Learning curve | Slightly steeper | More intuitive for GitHub users | | Self-hosted* | Full app or runner only | Runner only |

Recommendation: - If using GitLab, use GitLab CI/CD (unified platform). - If using GitHub, use GitHub Actions (tighter integration). - If using both, set up runners on each and use platform-specific syntax.

Both can run Claude Code equally well; the choice is about ecosystem fit and team preference.