CI/CD Runner Context

This feature is only available on Chainloop’s platform paid plans.

Chainloop allows you to gather optional runner context information and add it to your attestation as a CHAINLOOP_RUNNER_CONTEXT material. This information includes the basic information about your CI/CD environment. The Chainloop CLI Enterprise Edition (CLI EE) enables automatic gathering of detailed runner context by collecting repository security configuration data directly from your CI/CD environment. This feature captures:

Branch protection settings: push restrictions, history and deletion controls
Pull request protection settings: review requirements, dismissal rules, and conversation resolution policies
Commit protection settings: signing requirements
Repository access settings: teams with repository access and their members, collaborators with their effective roles, and custom repository roles

The collected context becomes part of your attestation data, providing auditable evidence of security controls during build and deployment and can be used with various branch protection policies.

Gathering Runner Context

Gathering the CI/CD runner context requires a few steps:

Installing Chainloop CLI Enterprise Edition (CLI EE)

The first step is to install Chainloop CLI EE. You can learn more about installing Chainloop CLI EE here or just run the following command:

curl -sfL https://dl.chainloop.dev/cli/install.sh | bash -s

The above command will install the latest version of Chainloop CLI EE, which includes the runner context gathering feature.

Create the Access Token

The second step is to create an access token for GitHub or GitLab. In order to gather the comprehensive runner context, Chainloop CLI EE requires an access token with the appropriate access level. Depending on the CI/CD platform of your choice, the access token will have different requirements. The token is only used by chainloop gather-runner-context on the runner to read your repository settings. It stays on the runner and is not sent to Chainloop.

GitHub
GitLab

We support two authentication methods for gathering runner context:

Enterprise GitHub AccountsIf you have an Enterprise GitHub account, you must create your GitHub Application at the enterprise level (not just at the organization level). Additionally:

Create the GitHub App in your Enterprise settings: Enterprise settings -> Developer settings -> GitHub Apps -> New GitHub App
Configure permissions at the enterprise level as described below
Install the app on the specific organizations and repositories within your enterprise
When using Personal Access Tokens (Method 2), you must use a Classic PAT (not fine-grained tokens) with the read:enterprise scope
Set the GITHUB_ENTERPRISE environment variable to your enterprise slug when running the gatherer

Why this matters: When an enterprise has roles, teams, or organization roles defined at the enterprise level and propagated down to organizations and repositories, the gatherer needs these specific permissions to retrieve the complete details of EnterpriseRole and BusinessTeam bypass actors. Without these permissions, this information will not be available through the GitHub API. This option for the moment is only available through GitHub App integration or Personal Access Token (Classic), not fine-grained tokens.Example:

export GITHUB_ENTERPRISE="your-enterprise-slug"
chainloop gather-runner-context --runner-token ${{ steps.generate-token.outputs.token }}

Method 1: Custom GitHub Application (Recommended)

For enterprise environments, you can create a custom GitHub Application to retrieve the data. This approach provides better security and management capabilities.Steps to register the GitHub Application:

Register a new GitHub Application in your Organization or Account profile, under Developer settings -> GitHub Apps -> New GitHub App
Add a Homepage URL since it’s a required parameter
Uncheck the Expire user authorization tokens checkbox
Uncheck the Webhook active checkbox
Select the following permissions:
- Repository:
  - Administration: read and write
  - Contents: read-only
- Organization:
  - Members: read-only
  - Administration: read-only
  - Custom Organization Roles: read-only
  - Custom Repository Roles: read-only
- Enterprise (for enterprise accounts only, in addition to the above):
  - Custom Enterprise Roles: read-only
  - Custom Organization Roles: read-only

Why these permissions are required:

Repository Administration (read and write): Write permission is required by GitHub’s API to access security-sensitive ruleset configuration details needed for policy enforcement. The gatherer only reads configuration data and does not modify any repository settings.
Repository Contents (read-only): Required to read repository metadata and basic information
Organization Members (read-only): Required to fetch team member information for teams with repository access
Organization Administration (read-only): Required to fetch all organization teams and determine which teams have access to specific repositories. This is particularly important for GitHub Apps, as they need this permission to discover organization-level team grants that aren’t visible through repository-specific API endpoints.
Custom Organization/Repository Roles (read-only): Required to resolve custom role names to their actual permissions and base roles
Enterprise Custom Roles (read-only) (Enterprise accounts only): Required to retrieve enterprise-level custom roles that may be assigned to teams or users

Click on This enterprise (for enterprise accounts) or select Any account (for non-enterprise accounts), depending on your desired installation scope
Once registered, click on Generate a private key. This will download a private key file - store it securely
Copy the App ID
To install the GitHub App on specific repositories or the entire organization, go to Developer settings -> GitHub Apps -> Your new App and click on Edit. Once the app is loaded, click on Install App in the left sidebar and follow the installation steps.

Store the credentials:

Store the App ID as a GitHub Actions variable (e.g., APP_ID)
Store the private key as a GitHub Actions secret (e.g., APP_PRIVATE_KEY)

Method 2: Personal Access Token (PAT)

Create a personal access token with the following permissions:

Only select repositories - select the repository you want to gather context data from
Repository permissions:
- Administration - Access: Read and write
- Contents - Access: Read-only
Organization permissions:
- Members - Access: Read-only
- Administration - Access: Read-only

Why these permissions are required:Repository Administration (Read and write): Write permission is required by GitHub’s API to access security-sensitive ruleset configuration details needed for policy enforcement. The gatherer only reads configuration data and does not modify any repository settings.Organization Administration (Read-only): Essential for comprehensive team access discovery, allowing the gatherer to fetch all organization teams and determine which have access to your repositories. Without this permission, only teams with explicit repository access grants will be visible.

For Enterprise GitHub accounts: You must use a Classic Personal Access Token (not a fine-grained token) with the additional read:enterprise scope. Fine-grained tokens do not support enterprise-level API endpoints.Once generated, store the personal access token in the CI/CD secrets (e.g., ADMIN_PERSONAL_ACCESS_TOKEN).

The default GITHUB_TOKEN of GitHub Actions does not have the Administration repository permission. With that token, classic branch protection rules cannot be read, so the policies report “no classic branch protection rule or ruleset” even when the branch is protected. Use a GitHub App or a personal access token with the permissions above.

For GitLab, create a personal, project or group access token with the read_api scope. The built-in CI_JOB_TOKEN cannot be used, because it cannot call the protected branches and project APIs.Use a token whose user has the Maintainer role. What each part of the runner context needs:

Data	Requirement
Protected branches and project settings	Any member who can read the code
Merge request approval settings and push rules	`Maintainer` role, and GitLab Premium or Ultimate

Without the Maintainer role, the collector reports permission errors for approval settings and push rules, and the policies that need them are skipped (see Skipped policies).Once generated, store the token in the CI/CD variables (e.g., GITLAB_TOKEN). chainloop gather-runner-context reads the GITLAB_TOKEN environment variable, or you can pass the token with --runner-token.For self-managed GitLab, the API URL is not detected automatically: pass it with --runner-api-url. It accepts the URL of your instance or its API URL (the CLI appends /api/v4 when it is missing). In GitLab CI, use the predefined CI_API_V4_URL variable.

Gather Runner Context

The third step is to gather the runner context data. The approach differs based on your CI/CD platform and authentication method:

GitHub - Using GitHub Application
GitHub - Using Personal Access Token
GitLab

When using a GitHub Application, you need to generate a token from the app credentials first, then use it with the Chainloop CLI. The following action allows you to retrieve

- name: Generate a token
  id: generate-token
  uses: actions/create-github-app-token@v2
  with:
    app-id: ${{ vars.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}

The key difference is using the actions/create-github-app-token action to generate a temporary token from your GitHub App credentials, which is then passed to the chainloop gather-runner-context command by using the ${{ steps.generate-token.outputs.token }} expression.

- name: Gather runner context data
  run: |
    chainloop gather-runner-context --runner-token ${{ steps.generate-token.outputs.token }}

For Enterprise GitHub accounts: Don’t forget to set the GITHUB_ENTERPRISE environment variable:

- name: Gather runner context data
  env:
    GITHUB_ENTERPRISE: your-enterprise-slug
  run: |
    chainloop gather-runner-context --runner-token ${{ steps.generate-token.outputs.token }}

Add the following command to your GitHub Actions workflow:

chainloop gather-runner-context --runner-token ${{ secrets.ADMIN_PERSONAL_ACCESS_TOKEN }}

For Enterprise GitHub accounts: Set the GITHUB_ENTERPRISE environment variable:

- name: Gather runner context data
  env:
    GITHUB_ENTERPRISE: your-enterprise-slug
  run: |
    chainloop gather-runner-context --runner-token ${{ secrets.ADMIN_PERSONAL_ACCESS_TOKEN }}

The above command will request the runner context data and store it in the file called runner-context.json.

Add the following command to your GitLab CI pipeline:

- chainloop gather-runner-context --runner-token $GITLAB_TOKEN

For self-managed GitLab, add the API URL of your instance. CI_API_V4_URL is a predefined GitLab CI variable. --runner-api-url accepts the instance URL or its API URL:

- chainloop gather-runner-context --runner-token $GITLAB_TOKEN --runner-api-url "$CI_API_V4_URL"

The above command will request the runner context data and store it in the file called runner-context.json.

Choose the Branches to Collect

Use --branches to limit the collected data to the branches you protect, for example:

chainloop gather-runner-context --branches "main,release/*"

Patterns follow fnmatch rules: * matches any characters except /, so release/* matches release/1.0 but not release/1.0/hotfix. ** also crosses /, so release/** matches both. The branches input of the branch protection policies uses the same rule. Related flags: --tags and --max-tags (default 15) for tag data, and --fetch-contributors to collect contributors.

Add the Runner Context to the Attestation

The fourth step is to add the runner context to the attestation. This can be done by adding the following command to your CI/CD pipeline, after chainloop gather-runner-context has written runner-context.json:

chainloop attestation add --name runner-context --value runner-context.json --kind CHAINLOOP_RUNNER_CONTEXT

The branch protection policy groups expect the material to be named runner-context. And that’s it, you are ready. You can now use the gathered runner context with the branch protection policies.

Skipped policies

When the collector cannot read some data, it records an error in the runner context and the policies that need that data are skipped instead of passing or failing. The skip reason says what to change in the token used by chainloop gather-runner-context:

Skip reason	What to add
GitHub authentication failed	Check that the token is valid and not expired
Insufficient permissions to read rulesets and branch protection (GitHub)	Use a GitHub App or token with the `Administration` repository permission. The default `GITHUB_TOKEN` does not have it
Insufficient permissions to read rulesets (GitHub)	Give the token access to the repository and the `Administration` repository permission
Insufficient permissions to read branches (GitHub)	The list of branches could not be read. Give the token the `Contents` and `Administration` repository permissions
Could not verify branch(es) …: the token cannot read classic branch protection, and the active rulesets alone do not pass this check (GitHub)	Use a GitHub App or token with the `Administration` repository permission. The default `GITHUB_TOKEN` does not have it
Could not verify branch(es) …: GitHub returned a temporary error while … read classic branch protection, and the active rulesets alone do not pass this check (GitHub)	Run `chainloop gather-runner-context` again
Could not verify branch(es) …: classic branch protection could not be read (the token lacks permission for some branches and GitHub returned a temporary error for others), and the active rulesets alone do not pass this check (GitHub)	Run `chainloop gather-runner-context` again with a GitHub App or token that has the `Administration` repository permission
Insufficient permissions to read repository collaborators and teams (GitHub, `repository-rules-change-restricted`)	Use a GitHub App or token that can read the repository’s collaborators and the organization’s teams and members
Failed to fetch repository data from GitHub (GitHub, `repository-rules-change-restricted`)	The runner context has no repository data. Check the `gather-runner-context` output for the error
Insufficient permissions to read the repository (GitHub, `repository-rules-change-restricted`)	Use a GitHub App or token that has access to the repository
GitLab authentication failed	Check that `GITLAB_TOKEN` (or `--runner-token`) is valid and not expired
Failed to fetch the project from GitLab	Check the `gather-runner-context` output. For self-managed GitLab, pass `--runner-api-url`
Insufficient permissions to read the GitLab project	Use a token with the `read_api` scope and access to the project
Insufficient permissions to read branches or branch protection (GitLab)	Use a token with the `read_api` scope and access to the project
Could not read the approval rules because of a temporary GitLab error (GitLab, `pr-review-required`)	Run `chainloop gather-runner-context` again
Insufficient permissions to read merge request approval settings (GitLab)	Use a token with the `read_api` scope from a `Maintainer`. Requires GitLab Premium or Ultimate
Insufficient permissions to read push rules (GitLab)	Use a token with the `read_api` scope from a `Maintainer`. Requires GitLab Premium or Ultimate

Classic branch protection that cannot be read

The GitHub branch and pull request policies do not skip the whole repository when the collector cannot read classic branch protection. This happens when the token lacks the Administration permission or GitHub returns a temporary error. The policies judge each branch on its own:

A branch passes when its active rulesets alone pass the check.
A branch whose classic rule was read is judged as usual.
Any other branch cannot be verified. If no branch fails for certain, the policy is skipped and the skip reason names the branches that could not be verified. If a branch fails, the policy reports only the failures.

Private repositories on GitHub Free

On GitHub Free, private repositories have no classic branch protection or rulesets. The branch and tag policies are not skipped. They report the missing protection and say to upgrade the plan or make the repository public.

Getting Started

Concepts

Guides

References

Misc

Gathering Runner Context

Installing Chainloop CLI Enterprise Edition (CLI EE)

Create the Access Token

Method 1: Custom GitHub Application (Recommended)

Method 2: Personal Access Token (PAT)

Gather Runner Context

Choose the Branches to Collect

Add the Runner Context to the Attestation

Skipped policies

Classic branch protection that cannot be read

Private repositories on GitHub Free

​Gathering Runner Context

​Installing Chainloop CLI Enterprise Edition (CLI EE)

​Create the Access Token

​Method 1: Custom GitHub Application (Recommended)

​Method 2: Personal Access Token (PAT)

​Gather Runner Context

​Choose the Branches to Collect

​Add the Runner Context to the Attestation

​Skipped policies

​Classic branch protection that cannot be read

​Private repositories on GitHub Free

Gathering Runner Context

Installing Chainloop CLI Enterprise Edition (CLI EE)

Create the Access Token

Method 1: Custom GitHub Application (Recommended)

Method 2: Personal Access Token (PAT)

Gather Runner Context

Choose the Branches to Collect

Add the Runner Context to the Attestation

Skipped policies

Classic branch protection that cannot be read

Private repositories on GitHub Free