CI Versions¶

This project runs in two CI flavors. Detect which one you are in via environment variables ($GITLAB_CI vs $GITHUB_ACTIONS) and behave accordingly.

Setting the Anthropic API key¶

The agent needs an ANTHROPIC_API_KEY. Store it in the platform's secret store— never in the repo, the pipeline YAML, or a component/action input.

gh secret set ANTHROPIC_API_KEY            # prompts for the value
# or: gh secret set ANTHROPIC_API_KEY --body "sk-ant-..." --repo bigg01/your-repo

- uses: bigg01/claude-ci-agent@v0.1.0-alpha.13
  with:
    prompt: "Fix the failing tests."
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

glab variable set ANTHROPIC_API_KEY "sk-ant-..." --masked --protected

include:
  - component: $CI_SERVER_FQDN/<group>/claude-ci-agent/claude-agent@v0.1.0-alpha.13
    inputs:
      prompt: "Fix the failing tests."

Zero-credential environment¶

The sandbox image ships with no ambient credentials— no global Git config, no SSH keys, no cloud profiles, and no long-lived tokens baked in. The agent is also instructed never to read host OS environment variables (see CLAUDE.MD). Every secret it needs is injected per run, scoped to that run by the CI platform's secret store, and gone when the job ends. The mechanism differs by platform:

Detecting the environment¶

if [ "$GITLAB_CI" = "true" ]; then
  echo "Running under GitLab CI"
elif [ "$GITHUB_ACTIONS" = "true" ]; then
  echo "Running under GitHub Actions"
fi

Personalities & triggers¶

The same image runs as one of two personalities, selected by the CI trigger. On GitLab both are shipped by the component as two jobs — claude-advisor (gated on merge_request_event) and claude-agent (gated on a non-empty $CLAUDE_TASK) — so a single include: wires up the full flow; you don't hand-write them (see Example pipelines). On GitHub the analog is the event-driven workflow.

Identity & attribution— who did what¶

Give every agent its own GitLab identity— a dedicated service account (bot user) whose access token it authenticates with. Never reuse a human's Personal Access Token, and never share one token across personalities or teams: if two agents push with the same credential, the audit log cannot tell them apart. The read-write Agent gets a write-scoped token; the read-only Advisor gets no push token at all (but still its own bot, so the review comments it posts are attributable).

Attribution then lands in three independent places that should always agree— if one disagrees, you have a misconfiguration:

1. GitLab audit log + MR author → the bot user the access token belongs to.
2. git log author/committer → the git identity (set it to match the bot).
3. Commit trailers + OTel attributes (claude.personality, ci.pipeline.id) → the specific run.

Naming example¶

One identity per (personality × team). For a read-write Agent on a payments team:

So a commit the agent makes carries, for example:

feat: handle null customer in checkout

Claude-Personality: agent
Claude-Bot: claude-agent-payments
Claude-Run: gitlab/pipeline/84213/job/99001
Claude-Model: claude-sonnet-4-6

Example pipelines¶

GitLab CI— using the claude-agent component¶

This section has two halves: the reusable component you reference (templates/claude-agent.yml), and a runnable example you copy (examples/gitlab/claude-ci-agent-test/). Read the reference to know what the component does, then copy the example to get a working pipeline.

1. Reference — the claude-agent component¶

A reusable GitLab CI/CD component ships with this project at templates/claude-agent.yml. A single include: adds both personalities as jobs — at parity with the GitHub workflow:

• claude-advisor (read-only) runs automatically on every merge_request_event: it reviews the diff and posts the verdict as an MR note.
• claude-agent (read-write) runs when $CLAUDE_TASK is non-empty (from the prompt input, or a pipeline variable supplied by a manual run / trigger token / webhook — GitLab has no native "MR comment" trigger): it applies the change on a new branch (branch_prefix + pipeline id) and opens a new MR, never the default branch.

Both jobs start an OTel Collector sidecar (nested Podman) when ELASTIC_OTLP_ENDPOINT is set, emit per-run cost, optionally fetch secrets via the OpenBao addon, and default to bypass-permissions ("YOLO") mode — safe here because the agent is fully contained. Each job also publishes claude-result.json (the raw run output — usage, cost, result) as a job artifact.

Inputs¶

2. Usage — minimal examples/gitlab pipeline¶

This is the minimal way to use the component: set one variable and write a single include:. The component ships both personalities, so the advisor auto-runs on merge requests and the agent runs whenever you hand it a task — no hand-written jobs.

Step 1 — set the Anthropic key as a CI/CD variable (this is how the key is provided; it is never a component input). In the consuming project (or group): Settings → CI/CD → Variables → Add variable:

Step 2 — include the component in your .gitlab-ci.yml:

stages:
  - test

include:
  - component: $CI_SERVER_FQDN/<group>/claude-ci-agent/claude-agent@v0.1.0-alpha.13
    inputs:
      prompt: "Fix the failing unit tests and commit the change."
      # api_key_variable: MY_KEY_NAME   # only if your variable isn't ANTHROPIC_API_KEY

The component reads the variable by name at runtime and exports it for the claude CLI — fail-fast if it's unset.

GitHub Actions— using the claude-ci-agent action¶

The GitHub analog of the GitLab component is a reusable Docker container action at action.yml. It runs the agent inside the same sandbox image and takes the same kind of inputs. Reference it from any workflow with uses::

name: Claude Agent
on: [workflow_dispatch]
jobs:
  agent:
    runs-on: ubuntu-latest
    steps:
      - uses: bigg01/claude-ci-agent@v1
        with:
          prompt: "Fix the failing unit tests and commit the change."
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Inputs¶

For the reusable action, the secret is passed via the secrets context (auto-masked in logs); the action itself never sees it as a plaintext input.

Complete scenario— GitLab + Jira, spec-driven¶

This ties the pieces together: a Jira issue is the spec, a status change kicks off GitLab, the read-write Agent implements it, the read-only Advisor grades the MR against that same spec, and the verdict flows back onto the ticket. The deeper rationale lives in Spec-driven development; this is the concrete GitLab wiring.

Timeline¶

1. A PO writes acceptance criteria on PROJ-142 and moves it to AI-Ready.
2. A Jira Automation rule fires a web request to GitLab's pipeline-trigger API, passing JIRA_ISSUE_KEY=PROJ-142.
3. The implement job pulls the issue → spec/PROJ-142.md, the Agent implements to spec, opens MR claude/PROJ-142, comments on Jira, and moves it to In Review.
4. The MR-open event runs the advisor job: it grades each criterion against the spec, posts PASS/FAIL on the MR and on Jira, and transitions the issue.
5. PASS → a human merges; a Smart Commit (PROJ-142 #close) closes the ticket. FAIL → a reviewer re-triggers the Agent on the same branch. The agent never self-merges.

Jira side— the trigger¶

A Jira Automation rule, When issue transitions to AI-Ready, Then Send web request (store the GitLab trigger token in Jira's secret vault, not inline):

POST https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/trigger/pipeline
form-encoded:
  token = {{ GitLab trigger token }}
  ref   = main
  variables[JIRA_ISSUE_KEY] = {{ issue.key }}

GitLab side— the complete .gitlab-ci.yml¶

Set as CI/CD variables (masked/protected, or minted at runtime by the OpenBao addon): ANTHROPIC_API_KEY, JIRA_URL, JIRA_TOKEN, GIT_PUSH_TOKEN (the Agent bot's write token), and the Jira transition IDs.

stages: [implement, review]

variables:
  AGENT_IMAGE: ghcr.io/bigg01/claude-ci-agent/claude-agent:0.1.0-alpha.13
  CLAUDE_MODEL: "claude-sonnet-4-6"
  CLAUDE_CODE_ENABLE_TELEMETRY: "1"
  OTEL_LOG_TOOL_CONTENT: "1"
  OTEL_EXPORTER_OTLP_ENDPOINT: http://localhost:4318

# Shared Jira helpers, injected into each job's before_script as shell functions.
.jira_fns: &jira_fns |
  jira_to_spec() {            # Jira issue → spec/<KEY>.md (Jira Cloud returns ADF JSON)
    mkdir -p spec
    curl -sS -H "Authorization: Bearer $JIRA_TOKEN" \
      "$JIRA_URL/rest/api/3/issue/$JIRA_ISSUE_KEY?fields=summary,description" \
    | python3 -c '
  import sys, json
  d = json.load(sys.stdin)["fields"]
  def t(n): return (n.get("text","")+"".join(t(c) for c in n.get("content",[]))) if isinstance(n,dict) else "".join(t(c) for c in n) if isinstance(n,list) else ""
  print("# %s\n\n%s" % (d["summary"], t(d.get("description") or {})))' > "spec/$JIRA_ISSUE_KEY.md"
  }
  jira_comment() {            # post the contents of $1 as a comment on the issue
    jq -Rs '{body:{type:"doc",version:1,content:[{type:"paragraph",content:[{type:"text",text:.}]}]}}' "$1" \
    | curl -sS -X POST -H "Authorization: Bearer $JIRA_TOKEN" -H "Content-Type: application/json" \
        "$JIRA_URL/rest/api/3/issue/$JIRA_ISSUE_KEY/comment" -d @-
  }
  jira_transition() {         # move the issue to transition id $1
    curl -sS -X POST -H "Authorization: Bearer $JIRA_TOKEN" -H "Content-Type: application/json" \
      "$JIRA_URL/rest/api/3/issue/$JIRA_ISSUE_KEY/transitions" -d "{\"transition\":{\"id\":\"$1\"}}"
  }

# ---- AGENT (read-write): Jira-triggered implementation -----------------------
implement:
  stage: implement
  image: $AGENT_IMAGE
  rules:
    - if: '$JIRA_ISSUE_KEY'            # only on the Jira-triggered pipeline
  before_script:
    - *jira_fns
    - git config user.name  "Claude Agent · payments"
    - git config user.email "claude-agent+payments@acme.dev"
  script:
    - jira_to_spec
    - |
      claude -p "Implement spec/$JIRA_ISSUE_KEY.md exactly. Satisfy every acceptance \
      criterion, add the tests it requires, follow CLAUDE.MD. Nothing out of scope." \
        --model "$CLAUDE_MODEL" --permission-mode bypassPermissions \
        --dangerously-skip-permissions
    # New branch named with the Jira key → GitLab/Jira auto-link the MR to the issue.
    - |
      git checkout -b "claude/$JIRA_ISSUE_KEY"
      git add -A
      git commit -m "feat($JIRA_ISSUE_KEY): implement from spec" \
        -m "Claude-Personality: agent" \
        -m "Claude-Run: gitlab/pipeline/$CI_PIPELINE_ID"
      git push "https://oauth2:${GIT_PUSH_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git" \
        "HEAD:claude/$JIRA_ISSUE_KEY" \
        -o merge_request.create \
        -o merge_request.title="$JIRA_ISSUE_KEY implement from spec"
    - echo "Claude opened an implementation MR for review." > _msg.txt && jira_comment _msg.txt
    - jira_transition "$JIRA_IN_REVIEW_ID"

# ---- ADVISOR (read-only): grade the MR against the spec ----------------------
advisor:
  stage: review
  image: $AGENT_IMAGE
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^claude\//'
  variables:
    JIRA_ISSUE_KEY: "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"   # claude/PROJ-142 → stripped below
  before_script:
    - *jira_fns
    - 'export JIRA_ISSUE_KEY="${JIRA_ISSUE_KEY#claude/}"'
  script:
    - |
      claude -p "You are the ADVISOR (read-only). Review this MR against \
      spec/$JIRA_ISSUE_KEY.md. For EACH acceptance criterion, state PASS or FAIL with \
      file:line evidence. Run the tests and linters. Note any out-of-scope work or \
      CLAUDE.MD violations. Write the verdict to review.md. Do NOT modify files." \
        --model "$CLAUDE_MODEL" --permission-mode bypassPermissions \
        --dangerously-skip-permissions
    # Post the verdict to the MR (bot API token) and to Jira, then transition.
    - |
      jq -Rs '{body: .}' review.md | curl -sS -X POST \
        -H "PRIVATE-TOKEN: $GIT_PUSH_TOKEN" -H "Content-Type: application/json" \
        "$CI_API_V4_URL/projects/$CI_MERGE_REQUEST_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes" -d @-
    - jira_comment review.md
    - |
      grep -q 'FAIL' review.md && jira_transition "$JIRA_CHANGES_REQUESTED_ID" \
                               || jira_transition "$JIRA_IN_REVIEW_ID"
  artifacts:
    paths: [review.md]
    expire_in: 1 week