chinmina-git-credentials-buildkite-plugin

Combines a Git credential helper with a chinmina-bridge helper agent to allow Buildkite agents securely authorize Github repository access.

The plugin contains a Git credential helper, enabled for the current step via an environment hook.

The credential helper calls chinmina-bridge when credentials for a GitHub repository are requested, supplying the result to Git in its expected format.

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

While this plugin can be used as a regular Buildkite plugin, it must be enabled on every step. This includes any steps configured in the pipeline configuration. This is difficult to implement and maintain; hence the strategy suggested.

Example

Add the following to your pipeline.yml:

steps:
  - command: ls
    plugins:
      - chinmina/chinmina-git-credentials#v1.1.0:
          chinmina-url: "https://chinmina-bridge-url"
          audience: "chinmina:your-github-organization"
          profiles: 
            - repo:default
            - org:buildkite-plugins

Configuration

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.

profiles (array)

Default: [repo:default]

An array of profile names to use when requesting a token from chinmina-bridge. Organization profiles are stored outside of chinmina-bridge, and must be set up in your deployment explicitly. For more information, see the Chinmina documentation.

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

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