Buildkite integration

Chinmina Bridge can be integrated as a Git credentials helper, or used directly to create a token.

Git authentication via helper

Tip

To use this Git authentication method, each Buildkite pipeline needs to be configured with an HTTPS Git URL in the Buildkite pipeline settings.

If SSH is referenced, the credential helper is not used.

There is a handy plugin that facilitates using Chinmina Bridge for Git authentication: the Chinmina Git Credentials Buildkite plugin.

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

Chinmina Bridge has an endpoint that returns credentials in the Git credential helper format.

Note

When used as a standard plugin, the Git credentials plugin needs to be active on all steps that pull the source repository. It is possible to do this on a step-by-step basis, but it’s … repetitive.

Enabling at the agent level is recommended (see below).

Configuration

On pipeline steps

Like other Buildkite plugins, this plugin can be enabled on commands steps. For example:

steps:
  - command: ls
    plugins:
      - chinmina/chinmina-git-credentials#v1.0.2:
          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: see below for instructions.

Enable on the agent (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 Chinmina Bridge authentication on all builds running on the agent.

Tip

If conditional activation is required, consider adding extra conditions to the environment hook. For example, enable the plugin based on the presence of an environment variable. The environment variable can be specified in the pipeline’s settings, enabling the plugin for all steps in a single pipeline.

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-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 plugin’s environment hook directly from the agent’s environment hook, specifying the plugin parameters directly.

   Execute plugin environment hook directly

   chimina_default_url="https://chinmina.url-to-instance.io";
   chimina_default_audience="chinmina:your-org"; # needs to match Chinmina Bridge configuration
   BUILDKITE_PLUGIN_CHINMINA_GIT_CREDENTIALS_VENDOR_URL="${BUILDKITE_PLUGIN_CHINMINA_GIT_CREDENTIALS_VENDOR_URL:-${chimina_default_url}}" \
     BUILDKITE_PLUGIN_CHINMINA_GIT_CREDENTIALS_AUDIENCE="${BUILDKITE_PLUGIN_CHINMINA_GIT_CREDENTIALS_AUDIENCE:-${chimina_default_audience}}" \
       source /buildkite/plugins/chinmina-git-credentials-buildkite-plugin/hooks/environment

   Note

   It is possible to clone the plugin in the environment hook as well, however this adds additional latency when every job starts.

Parameters

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

A recommendation: chinmina:your-github-organization. This is specific to the purpose of the token, and also scoped to the GitHub organization that tokens will be vended for. chinmina-bridge’s GitHub app is configured for a particular GitHub organization/user, so if you have multiple organizations, multiple agents will need to be running.