Getting started

Chinmina itself is a simple service, but it sits in the middle of an ecosystem. This means that a working installation requires a number of setup items.

Requirements

Before you start, there are a few things you’ll need to have:

1. A Buildkite organization, and a user with sufficient access to create an API token that can be used to get the details of any pipeline that is expected to be built.
2. A Github organization, and a user with sufficient permissions to create a Github App and install it into the organization.
3. Ability to deploy a server that can be accessed by the build agents (for example, an ECS service)
4. Ability to allow Buildkite agents to download and use a custom plugin or ability to add a plugin to the default settings of the Buildkite agents.

Buildkite setup

Create an API key with access to the REST API only with access to the read_pipelines scope.

Save the key securely: it will be provided to the server in a later step. Use a “bot” user to create the token if you can.

Github setup

1. Create an application in your Github organization, adding contents:read as the repository permissions. Note the Application ID.

2. Create and save a private key for the application

3. Install the application into the Github organization

   Choose the repositories the application will have access to. This is the limit of the resources that the application can vend tokens for.

Tip

Be sure to collect:

• the Application ID of the application created. This is found in the “About” section of the “General” page of the application.
• the Installation ID if the application in your organization. The Installation ID is the last segment of the URL on the installation configuration page.

Chinmina Bridge setup

The server is a Go application expecting to read configuration from environment variables, and can be deployed to a container runtime environment or a server. Container distribution is recommended.

It is possible to run multiple instances together in a cluster. While the internal cache is not shared between instances, this will only affect the latency, not the correctness.

Essential configuration

A minimal configuration of the service requires at least the configuration below. See the Configuration reference for details of all configuration.

• JWT_BUILDKITE_ORGANIZATION_SLUG required

  The slug of your Buildkite organization. This is the identifier of your organization that appears in your Buildkite URLs.

• JWT_AUDIENCE optional default: app-token-issuer

  The expected value of the aud claim in the JWT. Describes the intended audience of the issued JWT token, and guards against token reuse. While this is optional, it’s a good idea for this to be unique to the installation.

• BUILDKITE_API_TOKEN required

  The API token created for pipeline metadata lookups. Store securely and provide to the container securely.

• GITHUB_APP_PRIVATE_KEY required

  The PEM formatted private key of the created Github app. Store securely and provide to the container securely. This is a highly sensitive credential.

• GITHUB_APP_ID required

  The application ID of the Github application created above.

• GITHUB_APP_INSTALLATION_ID required

  The installation ID of the created Github application into your organization.

The service will start (by default) on port 8080, but this is configurable