Skip to main content
This feature is a proprietary feature and is of Chainloop platform.
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: required status checks, push restrictions, review dismissal policies, and admin enforcement rules
  • Pull request configurations: required reviewers, review dismissal rules, and branch update requirements
  • Commit protection details: signing requirements, status check policies, and custom protection rules
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 policies related to it.

​
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.
  • GitHub
  • GitLab
We support two authentication methods for gathering runner context: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-only
      • Contents: read-only
    • Organization:
      • Members: read-only
  6. Click on This enterprise (for enterprise accounts) or select Any account (for non-enterprise accounts), depending on your desired installation scope
  7. Once registered, click on Generate a private key. This will download a private key file - store it securely
  8. Copy the App ID
  9. 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-only
    • Contents - Access: Read-only
  • Organization permissions:
    • Members - Access: Read-only
Once generated, store the personal access token in the CI/CD secrets (e.g., ADMIN_PERSONAL_ACCESS_TOKEN).
Once generated, store the access token or GitHub App credentials in your CI/CD secrets as described above.

​
Request Runner Context During Build

The third step is to request the runner context during the build process. The approach differs based on your authentication method:
  • Using GitHub Application
  • Using Personal Access Token
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 to retrive

- 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 }}

​
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.