6.3 — CI review driver

Let your CI pipeline resolve VibeMap kanban reviews automatically. When your agent submits a criterion for review (vibemap_submit_for_review with a git_sha), your test workflow can post its outcome and the criterion moves to passed or failed — no human click required. Human resolution in the web app keeps working as the fallback, and agents can never resolve their own reviews.

1. Create a CI token

A CI token is a personal access token whose single scope is ci_review.

In the app, go to Account → Developer, enter a name, set the scope selector to CI review, and click Generate Key. The scope of every existing key is shown in the Scope column of the keys table.

⚠️ Pick the scope before you generate. A key's scope is fixed at creation — there is no way to change it afterwards. An Agent key posted to ci-result is rejected with 403 agents_cannot_self_resolve, which is the gate working as designed: the token that does the work must not be the token that passes it.

You can also mint one with an authenticated request, from a browser session on vibemap.ai:

curl -X POST https://vibemap.ai/api/account/keys \
  -H "Content-Type: application/json" \
  --cookie "$SESSION" \
  -d '{"name": "GitHub Actions CI", "scopes": ["ci_review"]}'

scopes takes exactly one entry — agent or ci_review, never both. The token comes back once, in the token field of the response.

A ci_review token can only post review outcomes. It cannot claim, submit, or edit anything, so it is safe to store as a CI secret. Add it to your repository as the VIBEMAP_CI_TOKEN secret.

2. Post the result from your workflow

POST /api/mcp/kanban/criterion/{criterionId}/ci-result

{
  "outcome": "passed",            // or "failed"
  "test_run_url": "https://github.com/you/repo/actions/runs/123",
  "git_sha": "<the sha that was tested>",
  "notes": "optional summary"
}

outcome and test_run_url are required; git_sha and notes are optional.

The criterion must be in_review. Responses: 200 resolved, 409 race (a human resolved it first), 403 wrong token type or scope, 422 illegal_transition (not in review) or 422 invalid_payload. Field-level reference: 6.2 — API reference.

3. GitHub Actions example

Your agent should write the criterion id it is working on somewhere the workflow can read — e.g. in the PR body as VibeMap-Criterion: <uuid>.

name: vibemap-review
on:
  pull_request:

jobs:
  test-and-report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        id: tests
        run: npm ci && npm test
        continue-on-error: true

      - name: Report result to VibeMap
        env:
          VIBEMAP_CI_TOKEN: ${{ secrets.VIBEMAP_CI_TOKEN }}
        run: |
          CRITERION_ID=$(echo "${{ github.event.pull_request.body }}" \
            | grep -oP 'VibeMap-Criterion: \K[0-9a-f-]{36}' | head -1)
          [ -z "$CRITERION_ID" ] && echo "No criterion id in PR body" && exit 0
          OUTCOME=$([ "${{ steps.tests.outcome }}" = "success" ] && echo passed || echo failed)
          curl -sf -X POST \
            "https://vibemap.ai/api/mcp/kanban/criterion/$CRITERION_ID/ci-result" \
            -H "Authorization: Bearer $VIBEMAP_CI_TOKEN" \
            -H "Content-Type: application/json" \
            -d "{\"outcome\":\"$OUTCOME\",\"test_run_url\":\"${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\",\"git_sha\":\"${{ github.event.pull_request.head.sha }}\"}"

      - name: Fail job if tests failed
        if: steps.tests.outcome != 'success'
        run: exit 1

What happens on failure

A failed outcome parks the criterion in failed with your notes and test_run_url attached. The assigned agent can then re-queue it (POST .../rework, documented in 6.2) — the retry automatically carries the review feedback — or a human can send it back from the board. An agent that isn't the assignee gets 403 not_assigned_agent.

Build evidence

On every resolution VibeMap records the build evidence (git_sha, diff_url, test_run_url, outcome) on the criterion and, when the sha matches a reported drift/sync run, links the criterion to the code-map nodes whose files it touched.

Where to go next

• Endpoint reference → 6.2 — Kanban tracker API reference
• The agent loop this closes → 6.1 — Kanban tracker user guide