Building the index

Each repository needs a carrick.json and a GitHub Actions workflow before Carrick can index it. Your coding agent writes both from the prompt that carrick init prints, runs the first scan if the repository has no index yet, and then opens a pull request. Once the pull request merges, the workflow updates the index on every push to main.

Index synchronization

After completing workspace setup, carrick init checks whether an index already exists in Carrick Cloud for your repositories:

• If an index exists: Carrick downloads the compiled index into .carrick/ by running a local deterministic pass and applying hosted classification rows. No model inference runs locally.
• If no index exists: Carrick reports that an initial scan is required, which your agent runs from the scaffold prompt below.

Generate configuration with your agent

When initialising repositories that do not yet have a carrick.json or scan workflow, carrick init provides a prompt to pass to your AI coding agent:

Run the carrick scaffold tool for owner/repo, passing its owner/repo as `repo`, and follow what it returns.

The scaffold tool generates the following configuration files:

• carrick.json: The repository service configuration derived from .carrick/proposal.json and local source files.
• .github/workflows/carrick.yml: The GitHub Actions workflow for continuous indexing.
• Agent instructions: Adds a ## Carrick instruction block to AGENTS.md or CLAUDE.md.

In a folder of several repositories, the prompt names each one, and the agent works through them one at a time. carrick index refuses to run while any repository in the folder has no carrick.json, so the scan runs once, after the last one.

Run the initial scan

If your repositories have not yet been indexed in Carrick Cloud, execute the initial scan from the workspace directory:

carrick index --detach

carrick index parses carrick.json, extracts routes, calls, and types, submits unresolved relationships for cloud classification, and uploads the compiled index to Carrick Cloud.

The --detach flag runs the scan in a background process, printing a scan ID and log location (.carrick/scan-<id>.log). This prevents agent execution timeouts on large codebases.

Monitor the progress of a background scan using carrick status:

carrick status

carrick status reports the active scan phase, file counts, and final completion status.

Manual configuration alternative

If you are configuring a repository manually without an agent:

1. Create a carrick.json at the repository root using carrick templates carrick.json or according to the carrick.json schema.
2. Generate the CI workflow with carrick templates workflow > .github/workflows/carrick.yml.
3. Run carrick index from your terminal to build and upload the index.

For Deno workspaces, ensure Deno 2.9.4 or newer is on PATH and prepare the module graph before scanning:

deno install --frozen --node-modules-dir=none

Commit the workflow to CI

Commit carrick.json and .github/workflows/carrick.yml to your repository on a branch, open a pull request, and merge it into your default branch.

The following workflow definition belongs in .github/workflows/carrick.yml:

name: Carrick

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  # Carrick Cloud sends this when a sibling repo in the same project changes
  # on its main branch, so this repo's cross-repo results catch up without
  # anyone pushing. If you add deploy steps to this file, gate them on
  # github.event_name so a sibling change never deploys this repo.
  repository_dispatch:
    types: [carrick-sibling-updated]
  # Rescan on demand (Actions tab, or: gh workflow run carrick.yml). After a
  # Carrick release the index only refreshes on the next scan.
  workflow_dispatch:
    inputs:
      full-scan:
        description: >-
          Re-analyze every file instead of reusing the cached answer for a file
          that has not changed. Slower and costs a full analysis; ask for it
          when Carrick has started extracting something it did not extract
          before, so the cache holds answers from before it could.
        type: boolean
        default: false

permissions:
  # Mint a short-lived OIDC token Carrick exchanges for keyless upload auth
  # (no upload secret to configure).
  id-token: write
  contents: read

jobs:
  carrick:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        # Full git history lets Carrick diff against the last scan and run incrementally.
        with:
          fetch-depth: 0
      - uses: carrick-tools/carrick@v1
        with:
          # Empty on every trigger but workflow_dispatch, which is the point:
          # a full re-analysis is asked for, never carried by a push.
          full-scan: ${{ inputs.full-scan }}

Key workflow configuration requirements:

• Branch matching: Ensure branches: [main] matches your repository’s default branch (main, master, develop).
• OIDC token permissions: The id-token: write permission is required for keyless upload authentication to Carrick Cloud.
• Repository dispatch: The carrick-sibling-updated trigger allows Carrick Cloud to refresh cross-service contracts when sibling repositories in the same project update.
• Fork security: Carrick automatically skips scanning pull requests originating from repository forks, because GitHub withholds Actions OIDC tokens on fork-generated PRs.

Related

• Quickstart is the short path from install to a first index.
• carrick.json explains monorepo service splitting and outbound call classification.
• CLI covers advanced flags, background scan management, and recheck budgets.
• PR comments describes automated GitHub pull request checks.