Skip to main content
This feature is only available on Chainloop’s platform paid plans.
The following functionality is considered experimental and subject to change.
Chainloop allows you to gather optional runner context information and add it to your workflow contract. This information will include 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, deletion controls, and admin enforcement rules
  • 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 -- --ee
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 Chainloop. 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.
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:
  1. Create the GitHub App in your Enterprise settings: Enterprise settings -> Developer settings -> GitHub Apps -> New GitHub App
  2. Configure permissions at the enterprise level as described below
  3. Install the app on the specific organizations and repositories within your enterprise
  4. When using Personal Access Tokens (Method 2), you must use a Classic PAT (not fine-grained tokens) with the read:enterprise scope
  5. 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 }}
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:
  1. Register a new GitHub Application in your Organization or Account profile, under Developer settings -> GitHub Apps -> New GitHub App
  2. Add a Homepage URL since it’s a required parameter
  3. Uncheck the Expire user authorization tokens checkbox
  4. Uncheck the Webhook active checkbox
  5. 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
  1. Click on This enterprise (for enterprise accounts) or select Any account (for non-enterprise accounts), depending on your desired installation scope
  2. Once registered, click on Generate a private key. This will download a private key file - store it securely
  3. Copy the App ID
  4. 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).

​
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:
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 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: 
chainloop att add --value ./runner-context.json --kind CHAINLOOP_RUNNER_CONTEXT
And that’s it, you are ready. You can now use the gathered runner context with the branch protection policies.