Index repositories in CI

Indexing started from Air Teams or the Air Context CLI on a developer machine is limited by repository size. In CI, the CLI runs with an organization service account instead of a personal login. It indexes much larger repositories, keeps the index current for everyone in your organization, and keeps personal tokens out of your pipelines. Re-runs are incremental: only the changes since the previously indexed revision are processed.

Prerequisites

An organization service account with AI access. An administrator creates the service account in JetBrains Console, grants it AI access, and makes sure it has an available credit limit. The account doesn't need any roles. Copy its client ID and client secret when they are displayed: the secret is shown only once, and you store both as CI secrets in the procedure below.
Service accounts never get AI access automatically. You must always explicitly grant AI access to a service account.
A checked-out Git repository. The CLI reads the repository ID and revision from Git, so run it in a checkout with a .git folder. A shallow clone is fine. A non-Git folder can be indexed too, but its repository ID may change between runs, which produces separate snapshots instead of updating one index.
A build agent with git, and curl on Linux and macOS. The CLI is a self-contained native binary; it needs no Docker image or JVM. Standard hosted runners such as ubuntu-latest work out of the box. Windows build agents work too, with the PowerShell installer; the examples below are written for Linux and macOS.

Set up CI indexing

Store the service account's client ID and client secret as masked secrets in your CI system, named JCP_ORG_SERVICE_CLIENT_ID and JCP_ORG_SERVICE_CLIENT_SECRET. The older names JCP_ORG_SERVICE_ID and JCP_ORG_SERVICE_SECRET still work.
The CLI picks these environment variables up automatically, so the pipeline doesn't need a jbcontext login step.
Add a step that installs the CLI:
curl -fsSL https://download.jetbrains.com/jetbrains-context/install.sh | bash
This installs the latest stable build to ~/.jbcontext/bin/jbcontext. To pin a version for reproducible pipelines:
curl -fsSL https://download.jetbrains.com/jetbrains-context/install.sh | bash -s -- --version=<version>
Add a step that runs the indexing from the repository checkout:
~/.jbcontext/bin/jbcontext --ci index
For what the --ci option changes, see What the --ci option changes.
Define the trigger, for example on every commit to the default branch or on a schedule. Index the default branch: searches from branches that have no index of their own fall back to it.

What the --ci option changes

--ci marks the run as unattended, for build agents: logs stream to stderr so that the build log keeps them, and index reports progress as plain log lines, uses all available CPU, and lifts the client-side repository size limits. It is a global option, so it goes before the command; the JBCONTEXT_CI=true environment variable does the same. The server lifts its own size limit only for runs authenticated with an organization service account.

Add -v to stream debug output as well.

Pipeline examples

Each example checks out the repository, installs the CLI, and runs jbcontext --ci index with the service account credentials in the environment.

Create the JCP_ORG_SERVICE_CLIENT_ID and JCP_ORG_SERVICE_CLIENT_SECRET repository secrets.

name: Index code

on: # define your own trigger, for example on every commit to main or on a schedule
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  index:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Air Context CLI
        run: curl -fsSL https://download.jetbrains.com/jetbrains-context/install.sh | bash
      - name: Index code
        run: ~/.jbcontext/bin/jbcontext --ci index
        env:
          JCP_ORG_SERVICE_CLIENT_ID: ${{ secrets.JCP_ORG_SERVICE_CLIENT_ID }}
          JCP_ORG_SERVICE_CLIENT_SECRET: ${{ secrets.JCP_ORG_SERVICE_CLIENT_SECRET }}
                

Add JCP_ORG_SERVICE_CLIENT_ID and JCP_ORG_SERVICE_CLIENT_SECRET as password-typed parameters. The example uses the TeamCity Kotlin DSL.

object IndexCode : BuildType({
    name = "Index code"

    vcs {
        root(MyVcsRoot) // VCS root to index
        checkoutMode = CheckoutMode.ON_AGENT // index needs the .git directory to identify the repository
    }

    params {
        password("env.JCP_ORG_SERVICE_CLIENT_ID", "credentialsJSON:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
        password("env.JCP_ORG_SERVICE_CLIENT_SECRET", "credentialsJSON:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
    }

    steps {
        script {
            name = "Install Air Context CLI"
            scriptContent = "curl -fsSL https://download.jetbrains.com/jetbrains-context/install.sh | bash"
        }
        script {
            name = "Index code"
            scriptContent = "~/.jbcontext/bin/jbcontext --ci index"
        }
    }

    triggers {
        // Define your own trigger, for example on every commit (vcs {}) or on a schedule
        schedule {
            schedulingPolicy = cron {
                dayOfWeek = "Mon-Fri"
                hours = "0"
                minutes = "0"
            }
            branchFilter = "+:<default>"
            triggerBuild = always()
            withPendingChangesOnly = false
        }
    }

    requirements {
        doesNotContain("teamcity.agent.jvm.os.name", "Windows") // the install step uses curl and bash
    }

    failureConditions {
        executionTimeoutMin = 120 // the first indexing run can take a while
    }
})
                

Define the JCP_ORG_SERVICE_CLIENT_ID and JCP_ORG_SERVICE_CLIENT_SECRET CI/CD variables as masked. GitLab exposes them to the job environment automatically.

stages:
  - index

index_code:
  stage: index

  image: ubuntu:24.04 # any Linux image with bash; curl and git are installed below

  # Define your own rules; this runs on pushes, schedules, and manual runs on the default branch
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

  before_script:
    - apt-get update && apt-get install -y curl git ca-certificates
    - curl -fsSL https://download.jetbrains.com/jetbrains-context/install.sh | bash

  script:
    - ~/.jbcontext/bin/jbcontext --ci index
                

Set up the git-creds, jcp-org-service-client-id, and jcp-org-service-client-secret credentials; the two service account values are Secret text credentials. The example is a Declarative Pipeline.

pipeline {

    agent any // needs curl and git available

    environment {
        JCP_ORG_SERVICE_CLIENT_ID = credentials('jcp-org-service-client-id')
        JCP_ORG_SERVICE_CLIENT_SECRET = credentials('jcp-org-service-client-secret')
    }

    stages {
        stage('Checkout code') {
            steps {
                git branch: 'main', credentialsId: 'git-creds', url: 'https://my.git.hosting/repo.git'
            }
        }
        stage('Install Air Context CLI') {
            steps {
                sh 'curl -fsSL https://download.jetbrains.com/jetbrains-context/install.sh | bash'
            }
        }
        stage('Index code') {
            steps {
                sh '~/.jbcontext/bin/jbcontext --ci index'
            }
        }
    }

}
                

Troubleshooting

JCP service account authentication failed: could not obtain an access token: The credential exchange was rejected. Check that JCP_ORG_SERVICE_CLIENT_ID and JCP_ORG_SERVICE_CLIENT_SECRET match the values shown in JetBrains Console and that the service account hasn't been deleted or disabled.
Indexing requests fail with 401 or 403: The credentials are valid, but the service account isn't allowed to index. Ask an administrator to check that the service account has AI access.
Repository is too large to be indexed: The server lifts its size limit only for runs authenticated with an organization service account. Check that JCP_ORG_SERVICE_CLIENT_ID and JCP_ORG_SERVICE_CLIENT_SECRET are set for the step that runs the indexing.
Project directory is not a git repository: The CLI didn't find a .git folder in the working directory and indexes it as a non-Git folder, so each run may produce a separate snapshot. Make sure that the checkout step runs before the indexing step and that the CLI runs from the repository root, or pass --project-path.

For more details, add -v to the index command: with --ci, the debug output streams to the build log. jbcontext doctor runs end-to-end self-tests: version, authentication, repository, index, and search. See also Troubleshooting and FAQ.

05 November 2026