Configuration

Chinmina uses environment variables for all configuration, as it is expected that it will be deployed in a container runtime.

Server

Configuration related to the core HTTP service.

SERVER_PORT

(default: 8080)

The port that the Chinmina service will bind to on startup.

SERVER_SHUTDOWN_TIMEOUT_SECS

(default: 25)

The number of seconds the server will wait for existing requests to complete when shutting down. Shutdown will occur once requests complete or the timeout occurs; whichever comes first.

SERVER_OUTGOING_MAX_IDLE_CONNS

(default: 100)

For outgoing HTTPS requests, the maximum total number of idle connections that are allowed.

SERVER_OUTGOING_MAX_CONNS_PER_HOST

(default: 20)

For outgoing HTTPS requests, the maximum connections that may be made per host. Given that Chinmina mainly targets Buildkite and GitHub API endpoints, this number is somewhat higher than might otherwise be usual.

Buildkite OIDC

JWT_BUILDKITE_ORGANIZATION_SLUG required

The organization slug for your Buildkite organization. This slug is used for API calls, and verifying OIDC tokens on incoming requests.

JWT_AUDIENCE

(default: app-token-issuer)

The audience that is expected on incoming OIDC tokens. This value must be supplied to buildkite-agent oidc create.

Tip

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.

Development settings

The following JWT settings are generally development only. In production, it’s expected that the default behaviour of retrieving the jwks.json directly from Buildkite will be the preferred method.

JWT_JWKS_STATIC

A static literal JWKS file for local testing. Use “make keygen” to generate a new key pair.

The local .envrc.local file can reference the generated key as follows:

jwks="$(cat .development/keys/jwk-sig-testing-pub.json)"
export JWT_JWKS_STATIC="${jwks}"

JWT_ISSUER_URL

(default: https://agent.buildkite.com)

Testing only. The issuer URL expected on incoming OIDC JWT tokens.

Buildkite API

BUILDKITE_API_TOKEN required

The Buildkite token used to access the Buildkite REST API. Should only be supplied the read_pipelines scope.

GitHub API

Tip

Either GITHUB_APP_PRIVATE_KEY or GITHUB_APP_PRIVATE_KEY_ARN is required.

GITHUB_APP_PRIVATE_KEY_ARN is strongly recommended where possible (see KMS configuration).

GITHUB_APP_PRIVATE_KEY required*

The GitHub Application private key in PEM format, supplied as text (not a file path).

GITHUB_APP_PRIVATE_KEY_ARN required*

The AWS KMS key (or alias) resource ARN that has been configured for use by Chinmina.

See the AWS KMS setup and configuration guide for more details.

GITHUB_APP_ID required

GitHub App ID of the app itself.

GITHUB_APP_INSTALLATION_ID required

The ID for the installation of the App in your organisation.

Open Telemetry

OBSERVE_ENABLED

(default: false)

When true, Open Telemetry traces and metrics will be published on the configured transport type (see OBSERVE_TYPE).

OBSERVE_METRICS_ENABLED

(default: true)

If the Open Telemetry target does not support metrics (e.g. Jaeger), set this to false. Only relevent when when OBSERVE_ENABLED is true.

OBSERVE_TYPE

(options: grpc | stdout default: grpc)

Set the outgoing transport to use for telemetry. GRPC is the default; stdout is only really useful for development situations where a telemetry server is not available.

OBSERVE_OTEL_LOG_LEVEL

(options: debug | info | warn default: info)

Configure internal Open Telemetry SDK logging. Any invalid value will be interpreted as disabled.

OBSERVE_SERVICE_NAME

(default: chinmina-bridge)

The identifying service name reported in traces and metrics.

OBSERVE_TRACE_BATCH_TIMEOUT_SECS

(default: 5)

The number of seconds to wait for a batch of spans before sending to the collector.

OBSERVE_METRIC_READ_INTERVAL_SECS

(default: 60)

The number of seconds to wait between metric read and send attempts. A shorter interval may be desirable in testing, or when higher precision is required.

OBSERVE_HTTP_TRANSPORT_ENABLED

(default: true)

If OBSERVE_ENABLED is also true, enable sub-traces for all outgoing HTTP requests. This allows tracing of Builkite and GitHub API traffic. This is very useful, but for some providers who charge by the number of spans, this may be a costly operation.

OBSERVE_CONNECTION_TRACE_ENABLED

(default: true)

When true, outgoing HTTP requests will be annotated with details of the connection process, e.g. DNS lookup time. Only effective when HTTP transport tracing is enabled.

OTEL_EXPORTER_OTLP_ENDPOINT

(default: http://localhost:4317)

The endpoint to which traces and metrics will be sent.

Tip

Standard Open Telemetry configuration is supported. See the Open Telemetry exporter configuration for all configuration variables available.