Customizing token permissions

By default, Chinmina Bridge vends GitHub tokens with contents:read and metadata:read access to the pipeline’s repository. Profiles extend this capability, allowing pipelines to request elevated permissions or access additional repositories.

Why customize permissions?

Elevated permissions for your repository

Use pipeline profiles when your pipeline needs to:

Write comments on pull requests during automated code review
Publish releases directly from the pipeline
Manage deployment status

Pipeline profiles grant additional permissions while keeping access scoped to the pipeline’s own repository.

Access to other repositories

Use organization profiles when your pipeline needs to access repositories beyond its own:

Publishing to organization-wide Homebrew taps or package registries
Loading Buildkite plugins from private repositories
Reading shared configuration or tooling repositories

Organization profiles provide controlled access to a static list of repositories across the organization.

Setting up profiles

Create the profile configuration file

Create a YAML file in a GitHub repository. This file will contain profile definitions for your organization.

pipeline:
  defaults:
    permissions: ["contents:read"]
  profiles:
    - name: "pr-commenter"
      permissions: ["contents:read", "pull_requests:write"]
    - name: "release"
      permissions: ["contents:write"]

organization:
  profiles:
    - name: "shared-plugins"
      repositories: ["buildkite-plugin-1", "buildkite-plugin-2"]
      permissions: ["contents:read"]

Configure Chinmina Bridge

Set the GITHUB_ORG_PROFILE environment variable to the location of your configuration file:
```
GITHUB_ORG_PROFILE=your-org:config-repo:path/to/profiles.yaml
```
Format: <OWNER>:<REPO>:<PATH_TO_FILE>

The GitHub App for Chinmina must have read access to this repository.
Verify the configuration

Check Chinmina logs at startup. If the profile file loads successfully, you’ll see profile statistics:
```
[info] Profiles loaded: 2 pipeline, 1 organization
```
If validation fails, errors will be logged and profiles will not be available.

Using profiles in pipelines

With the Chinmina Token plugin

The Chinmina Token plugin makes profile tokens available as environment variables.

Environment mode (declarative)

Specify profiles in the plugin configuration:

steps:
  - label: "Comment on PR"
    command: gh pr comment $BUILDKITE_PULL_REQUEST --body "Tests passed!"
    plugins:
      - chinmina/chinmina-token#v1.4.0:
          environment:
            - GITHUB_TOKEN=pipeline:pr-commenter

Profile prefixes:

pipeline:profile-name → pipeline profile
org:profile-name → organization profile

Library mode (dynamic)

For dynamic profile selection, use the chinmina_token helper script:

steps:
  - command: |
      # Select profile based on branch
      if [[ "$BUILDKITE_BRANCH" == "main" ]]; then
        export GITHUB_TOKEN=$(chinmina_token "pipeline:release")
      else
        export GITHUB_TOKEN=$(chinmina_token "pipeline:default")
      fi

      gh release create "$TAG" --notes "Release $TAG"
    plugins:
      - chinmina/chinmina-token#v1.4.0: {}

With the Git Credentials plugin

The Chinmina Git Credentials plugin can use profiles for Git operations:

steps:
  - command: git clone https://github.com/myorg/private-plugin.git
    plugins:
      - chinmina/chinmina-git-credentials#v1.6.0:
          profile: org:shared-plugins

Restricting profile access

Profiles restrict access to specific pipelines using claim-based matching. Sensitive permissions are only available to authorized pipelines.

Example: Only allow release profiles on the main branch:

pipeline:
  profiles:
    - name: "release"
      match:
        - claim: build_branch
          value: "main"
      permissions: ["contents:write"]

Pipelines on other branches will receive a 403 error when requesting this profile.

Next steps

See the profile reference for:

Complete field definitions
Match rule syntax and patterns
Available claims for authorization
Troubleshooting