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:

```text
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:

```bash
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`:

```bash
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](/carrick-json).
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:

```bash
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`:

```yaml
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](/quickstart) is the short path from install to a first index.
- [carrick.json](/carrick-json) explains monorepo service splitting and outbound call classification.
- [CLI](/cli) covers advanced flags, background scan management, and recheck budgets.
- [PR comments](/pr-output) describes automated GitHub pull request checks.