Ingesting your codebase

Creating the tarball

Pipe git ls-files into tar. This includes exactly the files tracked in your repo — your .gitignore is the source of truth, so build artifacts and dependencies are excluded automatically.

# Tar everything git tracks — respects .gitignore, no extra config needed
git ls-files -z --recurse-submodules | tar -czf repo.tar.gz --null -T -

Tip: uncommitted changes won't be included — commit (or stash to a branch) first. --recurse-submodules picks up submodule files; drop it if you only want the outer repo.

Adding context with .codepanion files

You can hand the agent extra context by committing .codepanion files anywhere in your repo: repo-wide (.codepanion), per-directory (src/payments/.codepanion), or per-file (src/payments/refund.ts.codepanion). They're indexed alongside your source, and the agent fetches the relevant ones on demand — so this is the place to record domain knowledge that isn't obvious from the code itself ("amounts are in cents," "Stripe for cards, Adyen for direct debit").

Sending the tarball

Post the gzipped archive to the ingest endpoint. Replace {tenantId} with your tenant ID.

curl -X POST https://api.codepanion.app/api/ingest/{tenantId} \
  -H "Authorization: Bearer $CODEPANION_TOKEN" \
  -H "Content-Type: application/gzip" \
  -H "X-Commit-Sha: $COMMIT_SHA" \
  --data-binary @repo.tar.gz

The API returns the snapshot ID and status; indexing then runs asynchronously (chunk → embed → store):

{
  "snapshotId": 42,
  "status": "pending",
  "codeBase": "default"
}

Running QA or staging alongside prod? You can tag an upload with an environment label and a snapshot name — see environments.

Multiple repositories (codebases)

One Codepanion tenant can index more than one repository. Each upload lands in a codebase; tell us which one with the X-CodeBase header (or a codebase query parameter):

curl -X POST "https://api.codepanion.app/api/ingest/$TENANT_ID" \
  -H "Authorization: Bearer $CODEPANION_TOKEN" \
  -H "Content-Type: application/gzip" \
  -H "X-Commit-Sha: $COMMIT_SHA" \
  -H "X-CodeBase: billing-service" \
  --data-binary @repo.tar.gz

Codebase names are lowercase letters, digits and hyphens (anything else is normalised — acme/Widget API becomes acme-widget-api), and a codebase is created automatically the first time you ingest into it. Leave the header off and the upload goes to your default codebase, so single-repo setups need no configuration. With keyless OIDC ingest (below), each repository lands in a codebase named after it automatically. The agent searches across all your codebases by default and can scope an investigation to one; you can rename their display names in Settings → Codebases. Environment labels are independent of codebases — a qa label applies within whichever codebase you upload to.

CI example: GitHub Actions

A complete workflow that ingests on every push to main, using plain curl:

name: Ingest codebase

on:
  push:
    branches: [main]

jobs:
  ingest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Create tarball
        run: git ls-files -z --recurse-submodules | tar -czf repo.tar.gz --null -T -

      - name: Send to Codepanion
        env:
          CODEPANION_TOKEN: ${{ secrets.CODEPANION_TOKEN }}
          TENANT_ID: ${{ vars.CODEPANION_TENANT_ID }}
        run: |
          curl -X POST "https://api.codepanion.app/api/ingest/$TENANT_ID" \
            -H "Authorization: Bearer $CODEPANION_TOKEN" \
            -H "Content-Type: application/gzip" \
            -H "X-Commit-Sha: $GITHUB_SHA" \
            --data-binary @repo.tar.gz \
            --fail --silent --show-error

Store CODEPANION_TOKEN as a repository secret and CODEPANION_TENANT_ID as a repository variable.

Keyless ingest (recommended): GitHub Actions OIDC

Even better — don't store a token at all. With GitHub's OpenID Connect your workflow proves its identity per run; Codepanion validates that short-lived token and checks the repository against an allowlist you manage in Settings → API key. Nothing to store, nothing to rotate, and nothing for a leaked CI secret to expose.

name: Ingest codebase

on:
  push:
    branches: [main]

permissions:
  id-token: write   # mint the short-lived OIDC token
  contents: read

jobs:
  ingest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: git ls-files -z --recurse-submodules | tar -czf repo.tar.gz --null -T -
      - name: Send to Codepanion (keyless)
        env:
          TENANT_ID: ${{ vars.CODEPANION_TENANT_ID }}
        run: |
          TOKEN=$(curl -s -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=codepanion-ingest" | jq -r .value)
          curl -X POST "https://api.codepanion.app/api/ingest/$TENANT_ID" \
            -H "Authorization: Bearer $TOKEN" \
            -H "Content-Type: application/gzip" \
            -H "X-Commit-Sha: $GITHUB_SHA" \
            --data-binary @repo.tar.gz --fail --silent --show-error

Add your-org/your-repo to the allowlist in Settings → API key. No repository secret needed — only the tenant ID variable.