---
name: "Chinmina Token"
description: "Provides GitHub token retrieval from Chinmina in two modes:

**Library Mode** (no `environment` parameter): Adds `chinmina_token` script to
PATH for manual token retrieval in agent scripts.

**Environment Mode** (`environment` parameter present): Automatically exports
tokens to specified environment variables.

The helper agent (separate) is accessed via HTTP, using the Buildkite Agent
OIDC token as its authorization.
."
author: "chinmina"
repo: "chinmina-token-buildkite-plugin"
stars: 0
official: false
version: "v1.4.0"
lastUpdated: "2026-01-09T00:59:52.000Z"
---

# chinmina-token-buildkite-plugin

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

> [!NOTE]
> Refer to the [Chinmina documentation][chinmina-integration] 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:

```yml
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:

```shell
# 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][git-credentials] plugin.

<details>
<summary>Alternative approach</summary>

<div>
It's also possible to install the library function using the plugin parameters,
but this is no longer necessary.

```shell
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
```

</div>
</details>

#### Using defaults in pipelines

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

```yml
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):

```yml
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:

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

Then in your scripts:

```bash
# 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

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

## 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):

```bash
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`][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`][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

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

**Equivalent manual approach:**

```bash
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`:

```shell
# 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

[chinmina-bridge]: https://chinmina.github.io/introduction/
[chinmina-integration]: https://chinmina.github.io/guides/buildkite-integration/
[git-credentials]: https://github.com/chinmina/chinmina-git-credentials-buildkite-plugin/
[organization-profiles]: https://chinmina.github.io/reference/organization-profile/