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.

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: A library plugin that adds a chinmina_token script to fetch a GitHub token from Chinmina Bridge.

Note

The plugins can be configured as usual in pipeline steps, but also in the Buildkite agent hooks. Agent hooks ensure that Chinmina is integrated into all pipelines that run on the agent, without the need for further configuration.

For Git authentication integration in particular it is highly recommended to use agent hooks (see below).

Configuring the extensions in a pipeline

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.

Using them in a pipeline should then look quite familiar:

steps:
  - command: ls
    plugins:
      # Git authentication via helper
      - chinmina/chinmina-git-credentials#v1.0.2:
          chinmina-url: "https://chinmina-bridge-url"
          audience: "chinmina:your-github-organization"
      # Token helper script
      - chinmina/chinmina-token#v1.0.1:
          chinmina-url: "https://chinmina-bridge-url"
          audience: "chinmina:your-github-organization"

In order for this plugin to work for a whole pipeline, it must be enabled on every step. This includes any steps configured in the pipeline configuration.

In practice, this becomes quite repetitive and prone to misconfiguration. The only other option available is configuring the plugin on the agent.

Tip

To use the Git authentication integration, 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.

Enabling on the agent (for all pipelines)

This method enables the plugin in the agent environment hook, using a plugin version that has been downloaded in the agent bootstrap.

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

If more control over activation of this feature is required, consider adding extra conditions as code to the environment hook. For example, it’s possible to enable the plugin based on the presence of an environment variable. Then it will be enabled in a consistent way for every pipeline that defines the environment variable in the pipeline settings.

Note

The steps below show implementation for chinmina-git-credentials-buildkite-plugin and can be similarly implemented for chinmina-token-buildkite-plugin as well.

1. Alter the agent bootstrap hook to clone the plugin source to the agent so it can be activated by any step.

   plugin_repo="https://github.com/chinmina/chinmina-token-buildkite-plugin.git"
   plugin_version="v1.0.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}"

2. Call the plugin’s environment hook directly from the agent’s environment hook, specifying the plugin parameters directly.

   Execute plugin environment hook directly

   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

   Note

   It is possible to clone the plugin in the environment hook but this means the plugin is cloned when every job starts, adding additional latency.

Getting a token directly

The chinmina-token plugin is a library plugin that adds a chinmina_token function to the step’s environment.

The following example shows how to use the chinmina_token function to get a token and use it with the GitHub CLI to download a release asset from a private repository.

# use the helper function to get a token
export GITHUB_TOKEN=$(chinmina_token "org:profile-name")

# The GH CLI will use GITHUB_TOKEN as its authorization for any API requests:

# ... show this to the console
gh auth status

# ... download a release from a private repo
gh releases download --repo "${repo}" \
  --pattern "release-file=${arch}.zip" \
  --dir "${directory}" \
  "${tag}"

How Chinmina-integrated Git authentication works

The Chinmina Git Credentials Buildkite plugin integrates Chinmina with Git, allowing authentication tokens to be retrieved on-demand in the Git authentication flow.

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.