Buildkite integration

There are two broad ways that Chinmina Bridge can be integrated with Buildkite pipelines:

1. Git authentication: This allows Buildkite pipelines to authenticate with GitHub using a token that is scoped to the pipeline, and can be used to access private repositories.

2. Token generation: This allows Buildkite pipelines to generate a GitHub token that can be used to access private repositories, such as downloading private release assets. Tokens can be exported automatically as environment variables or retrieved programmatically via a helper script.

Git authentication integration removes the need to configure SSH deploy keys for each repository, and token generation is a replacement for long-lived GitHub Personal Access Tokens (PATs) stored in secrets.

Each use case is integrated using a Buildkite plugin:

• Chinmina Git Credentials: configures a Git credentials helper that uses Chinmina Bridge to authenticate with GitHub.
• Chinmina Token: Retrieves GitHub tokens from Chinmina Bridge, either by automatically exporting them as environment variables or by adding a chinmina_token helper script for dynamic token retrieval.

Recommended setup

The plugins can be configured in individual pipeline steps, but production installations should load the plugins in the Buildkite agent bootstrap and environment hooks.

This configuration ensures that Chinmina is integrated into all pipelines that run on the agent, without the need for further configuration. See “Enabling on the agent” for setup instructions.

This is the only practical way to use Chinmina Bridge for Git authentication in particular.

Configuration

Full documentation for each plugin:

• Chinmina Git Credentials
• Chinmina Token

Collect the following information from your Chinmina Bridge instance:

1. The URL of the Chinmina Bridge instance, e.g. https://chinmina-bridge.your-organization.io.
2. The audience for the OIDC token, e.g. chinmina:your-github-organization.

If the audience doesn’t match the value expected by Chinmina Bridge, all requests will fail.

Prerequisites

1. If openssl is present on the agent, both plugins will use it to encrypt a cached OIDC token, speeding up successive token requests in the same job.
2. The chinmina-token plugin requires jq to be installed on the Buildkite agent.

Using tokens in pipelines

The examples below show full plugin configuration including chinmina-url and audience parameters. When agent-level defaults are configured (see “Enabling on the agent” below), these parameters can be omitted from pipeline configuration.

Environment mode (declarative)

The simplest way to use tokens is via the environment parameter, which automatically exports tokens as environment variables. This is the recommended approach for most use cases.

steps:
  - label: "Deploy to production"
    command: |
      # GITHUB_TOKEN is automatically available
      gh release download --repo myorg/myrepo --pattern "*.zip"
    plugins:
      - chinmina/chinmina-token#v1.2.0:
          chinmina-url: "https://chinmina-bridge-url"
          audience: "chinmina:your-github-organization"
          environment:
            - GITHUB_TOKEN=repo:default

Tip

Tokens retrieved from Chinmina Bridge are automatically redacted from build logs.

Multiple tokens

For workflows requiring multiple tokens (e.g., accessing different organizations or profiles):

steps:
  - label: "Build with private dependencies"
    command: |
      # Multiple tokens available for different purposes
      npm config set //npm.pkg.github.com/:_authToken "$GITHUB_NPM_TOKEN"
      npm install

      # Deploy using different token
      gh release create --repo myorg/releases "$VERSION"
    plugins:
      - chinmina/chinmina-token#v1.2.0:
          chinmina-url: "https://chinmina-bridge-url"
          audience: "chinmina:your-github-organization"
          environment:
            - GITHUB_TOKEN=repo:default
            - GITHUB_NPM_TOKEN=org:npm-packages

Library mode (dynamic)

For dynamic token selection or complex scripting scenarios, use the chinmina_token helper script directly. When the plugin is configured without an environment parameter, it adds the chinmina_token script to PATH.

steps:
  - plugins:
      - chinmina/chinmina-token#v1.2.0:
          chinmina-url: "https://chinmina-bridge-url"
          audience: "chinmina:your-github-organization"

Then in your scripts:

# Dynamically select profile based on environment
if [[ "$ENVIRONMENT" == "production" ]]; then
  export GITHUB_TOKEN=$(chinmina_token "org:prod-profile")
else
  export GITHUB_TOKEN=$(chinmina_token "org:staging-profile")
fi

# Or get a token for the repository
export GITHUB_TOKEN=$(chinmina_token "repo:default")

# Use with gh CLI
gh release download --repo "${repo}" \
  --pattern "release-file-${arch}.zip" \
  --dir "${directory}" \
  "${tag}"

When to use each approach

Use Case	Recommended Approach
Static token needs known upfront	environment array (declarative)
Multiple tokens for different services	environment array
Dynamic profile selection	chinmina_token script
Conditional token logic	chinmina_token script
Token needed only in specific conditions	chinmina_token script

Using Git credentials for authentication

The Chinmina Git Credentials plugin enables Git operations to authenticate with GitHub using tokens from Chinmina Bridge.

steps:
  - command: git clone https://github.com/myorg/private-repo.git
    plugins:
      - chinmina/chinmina-git-credentials#v1.0.2:
          chinmina-url: "https://chinmina-bridge-url"
          audience: "chinmina:your-github-organization"

Tip

Each Buildkite pipeline needs to be configured with an HTTPS Git URL in the Buildkite pipeline settings.

Alternatively, the BUILDKITE_REPO value can be overridden in the agent environment hook to use an HTTPS URL instead of the SSH form.

If SSH is configured, Git will ignore the credential helper.

How it works

There are two cooperating parts to the plugin:

1. An environment hook to configure a Chinmina Git credentials helper using environment variables.
2. A Chinmina Bridge Git credentials helper. This is a simple bash script that will be called by Git (as configured in the environment).

When Git clones or fetches a repository, it calls the Credential Helper, which defers to Chinmina (authenticated with an OIDC token for this pipeline). Chinmina returns a result in the Git credentials helper format containing the required username, and the token created for the pipeline.

Enabling on the agent (for all pipelines)

Tip

This is the recommended way to integrate Chinmina with Buildkite, especially for Git authentication. Using the plugins on a step-by-step basis is inconvenient and inefficient.

This method enables the plugins in the agent environment hook, using plugin versions that have been downloaded in the agent bootstrap.

This will enable the functionality to fetch GitHub tokens and authenticate via Chinmina Bridge on all builds running on the agent.

If more control over activation of this feature is required, add extra conditions as code to the environment hook. For example, enable the plugin based on the presence of an environment variable. This activates the plugin consistently for every pipeline that defines the environment variable in the pipeline settings.

1. Alter the agent bootstrap hook to clone both plugin sources to the agent so they can be activated by any step.

   # Chinmina Token plugin
   plugin_repo="https://github.com/chinmina/chinmina-token-buildkite-plugin.git"
   plugin_version="v1.2.0"
   plugin_dir="/buildkite/plugins/chinmina-token-buildkite-plugin"
   
   [[ -d "${plugin_dir}" ]] && rm -rf "${plugin_dir}"
   
   GIT_CONFIG_COUNT=1 \
   GIT_CONFIG_KEY_0=advice.detachedHead \
   GIT_CONFIG_VALUE_0=false \
     git clone --depth 1 --single-branch --no-tags \
       --branch "${plugin_version}" -- \
       "${plugin_repo}" "${plugin_dir}"
   
   # Chinmina Git Credentials plugin
   plugin_repo="https://github.com/chinmina/chinmina-git-credentials-buildkite-plugin.git"
   plugin_version="v1.0.2"
   plugin_dir="/buildkite/plugins/chinmina-git-credentials-buildkite-plugin"
   
   [[ -d "${plugin_dir}" ]] && rm -rf "${plugin_dir}"
   
   GIT_CONFIG_COUNT=1 \
   GIT_CONFIG_KEY_0=advice.detachedHead \
   GIT_CONFIG_VALUE_0=false \
     git clone --depth 1 --single-branch --no-tags \
       --branch "${plugin_version}" -- \
       "${plugin_repo}" "${plugin_dir}"

2. Call the plugins’ environment hooks directly from the agent’s environment hook, specifying the plugin parameters directly. These defaults will be used by all pipelines unless explicitly overridden.

   Execute plugin environment hooks directly

   # Configure Chinmina Token plugin
   BUILDKITE_PLUGIN_CHINMINA_TOKEN_CHINMINA_URL="${BUILDKITE_PLUGIN_CHINMINA_TOKEN_CHINMINA_URL:-https://chinmina.url-to-instance.io}" \
   BUILDKITE_PLUGIN_CHINMINA_TOKEN_AUDIENCE="${BUILDKITE_PLUGIN_CHINMINA_TOKEN_AUDIENCE:-chinmina:your-org}" \
       source /buildkite/plugins/chinmina-token-buildkite-plugin/hooks/environment
   
   # Configure Chinmina Git Credentials plugin
   BUILDKITE_PLUGIN_CHINMINA_GIT_CREDENTIALS_CHINMINA_URL="${BUILDKITE_PLUGIN_CHINMINA_GIT_CREDENTIALS_CHINMINA_URL:-https://chinmina.url-to-instance.io}" \
   BUILDKITE_PLUGIN_CHINMINA_GIT_CREDENTIALS_AUDIENCE="${BUILDKITE_PLUGIN_CHINMINA_GIT_CREDENTIALS_AUDIENCE:-chinmina:your-org}" \
       source /buildkite/plugins/chinmina-git-credentials-buildkite-plugin/hooks/environment

   With this configuration, pipelines no longer need to specify chinmina-url and audience parameters:

   plugins:
     - chinmina/chinmina-token#v1.2.0:
         environment:
           - GITHUB_TOKEN=repo:default

   Note

   The bootstrap hook is only run when the agent starts. Cloning the plugins in the bootstrap hook is more efficient than doing so in the environment hook, and also faster.