chinmina-token-buildkite-plugin

A Buildkite plugin for retrieving GitHub tokens from Chinmina for the current repository or organizational profiles. Tokens can be automatically exported as environment variables or retrieved programmatically via the chinmina_token helper script.

[!NOTE] Refer to the Chinmina documentation for detailed information about configuring and using this plugin effectively.

The documentation recommends configuring the token plugin at the agent level, so the chinmina_token function is available to all scripts, and the default configuration for the current plugin environment is configured.

When the plugin is installed at the agent level, the environment parameter is all that needs to be supplied.

Requirements

• jq - Used for parsing plugin configuration and extracting version information

Getting Started

The simplest way to use this plugin is to declare the tokens you need as environment variables:

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

[!TIP] All tokens retrieved from Chinmina Bridge are automatically redacted from build logs.

Agent configuration

If you install the plugin on the agent by default (in the bootstrap of the Elastic Stack, for example), you can default the configuration for all pipelines using environment variables AND make use of the chinmina_token library function without further configuration.

Plugin defaults with library function (recommended)

Add the following to the agent environment hook:

# set the default configuration for this and the git credentials plugin
export CHINMINA_DEFAULT_URL="https://chinmina-bridge.example.com"
export CHINMINA_DEFAULT_AUDIENCE="chinmina:your-organization"

# add the library function to the path
source /buildkite/plugins/chinmina-token-buildkite-plugin/hooks/environment

This installs the library function and sets the shared default configuration for this plugin and the sibling Git credentials plugin.

BUILDKITE_PLUGIN_CHINMINA_TOKEN_CHINMINA_URL="${BUILDKITE_PLUGIN_CHINMINA_TOKEN_CHINMINA_URL:-https://chinmina-bridge.example.com}" \
  BUILDKITE_PLUGIN_CHINMINA_TOKEN_AUDIENCE="${BUILDKITE_PLUGIN_CHINMINA_TOKEN_AUDIENCE:-chinmina:your-organization}" \
    source /buildkite/plugins/chinmina-token-buildkite-plugin/hooks/environment

Using defaults in pipelines

With either approach, pipelines can omit the URL and audience:

steps:
  - label: "Deploy to production"
    command: |
      # GITHUB_TOKEN is automatically available
      gh release download --repo myorg/myrepo --pattern "*.zip"
    plugins:
      - chinmina/chinmina-token#v1.3.1:
          environment:
            - GITHUB_TOKEN=pipeline:default

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.3.1:
          chinmina-url: "https://chinmina-bridge-url"
          audience: "chinmina:your-github-organization"
          environment:
            - GITHUB_TOKEN=pipeline:default
            - GITHUB_NPM_TOKEN=org:npm-packages

Advanced Usage

For dynamic token selection or complex scripting scenarios, use the chinmina_token helper script directly:

steps:
  - plugins:
      - chinmina/chinmina-token#v1.3.1:
          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 "pipeline:default")

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

When to Use Each Approach

Configuration

Environment Variables

For organization-wide consistency, you can set default values using environment variables that apply when plugin parameters are not specified:

• CHINMINA_DEFAULT_URL: Default Chinmina Bridge URL
• CHINMINA_DEFAULT_AUDIENCE: Default OIDC audience

Priority order:

1. Plugin parameters (highest)
2. CHINMINA_DEFAULT_* environment variables
3. CHINMINA_TOKEN_LIBRARY_FUNCTION_* environment variables (backward compatibility)
4. Built-in defaults (audience only: chinmina:default)

Set these in your agent’s environment hook (/etc/buildkite-agent/hooks/environment or via agent bootstrap configuration):

export CHINMINA_DEFAULT_URL="https://chinmina-bridge.company.internal"
export CHINMINA_DEFAULT_AUDIENCE="chinmina:production"

With environment variables set, pipelines can omit common configuration or override when needed for specific cases.

chinmina-url (Required, string)

The URL of the chinmina-bridge helper agent that vends a token for a pipeline. This is a separate HTTP service that must be accessible to your Buildkite agents.

audience (string)

Default: chinmina:default

The value of the aud claim of the OIDC JWT that will be sent to chinmina-bridge. This must correlate with the value configured in the chinmina-bridge settings.

Recommendation: chinmina:your-github-organization

This value should be specific to the purpose of the token and scoped to the GitHub organization that tokens will be vended for. Since chinmina-bridge’s GitHub app is configured for a particular GitHub organization/user, multiple agents are needed for multiple organizations.

environment (array of strings)

Automatically export environment variables containing tokens from specified profiles. Each entry uses the format VAR_NAME=profile.

Profile formats

• pipeline:default - Token for the current repository
• org:profile-name - Token for an organizational profile

Example

environment:
  - GITHUB_TOKEN=pipeline:default
  - GITHUB_NPM_TOKEN=org:npm-packages
  - GITHUB_HOMEBREW_TOKEN=org:homebrew-tap

Equivalent manual approach:

export GITHUB_TOKEN=$(chinmina_token "pipeline:default")
export GITHUB_NPM_TOKEN=$(chinmina_token "org:npm-packages")
export GITHUB_HOMEBREW_TOKEN=$(chinmina_token "org:homebrew-tap")

Features

• Tokens are automatically redacted from build logs
• Fails fast if any token retrieval fails
• Validates environment variable names and profile values

Developing

Run tests and plugin linting locally using docker compose:

# Buildkite plugin linter
docker compose run --rm lint

# Bash tests
docker compose run --rm tests

# Specific test file
docker compose run --rm tests tests/chinmina_token.bats

Contributing

Contributions are welcome! Raise a PR, and include tests with your changes.

1. Fork the repo
2. Make the changes
3. Run the tests and linter
4. Commit and push your changes
5. Send a pull request