Skip to content
Chinmina Chinmina

Configuration

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

Server

Section titled “Server”

Configuration related to the core HTTP service.

SERVER_PORT
Section titled “SERVER_PORT”

(default: 8080)

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

SERVER_SHUTDOWN_TIMEOUT_SECS
Section titled “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
Section titled “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
Section titled “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

Section titled “Buildkite OIDC”
JWT_BUILDKITE_ORGANIZATION_SLUG required
Section titled “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
Section titled “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.

Development settings

Section titled “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
Section titled “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:

Terminal window
jwks="$(cat .development/keys/jwk-sig-testing-pub.json)"
export JWT_JWKS_STATIC="${jwks}"
JWT_ISSUER_URL
Section titled “JWT_ISSUER_URL”

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

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

Buildkite API

Section titled “Buildkite API”
BUILDKITE_API_TOKEN required
Section titled “BUILDKITE_API_TOKEN ”required

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

GitHub API

Section titled “GitHub API”
GITHUB_APP_PRIVATE_KEY required
Section titled “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
Section titled “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
Section titled “GITHUB_APP_ID ”required

GitHub App ID of the app itself.

GITHUB_APP_INSTALLATION_ID required
Section titled “GITHUB_APP_INSTALLATION_ID ”required

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

GITHUB_ORG_PROFILE
Section titled “GITHUB_ORG_PROFILE”

The location of your organization profile, if in use. This should be a triplet of the form <OWNER>:<REPO>:<PATH_TO_FILE>. No other format is accepted.

The contents of this organization profile must conform to the organization profile configuration format.

Open Telemetry

Section titled “Open Telemetry”
OBSERVE_ENABLED
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “OBSERVE_SERVICE_NAME”

(default: chinmina-bridge)

The identifying service name reported in traces and metrics.

OBSERVE_TRACE_BATCH_TIMEOUT_SECS
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “OTEL_EXPORTER_OTLP_ENDPOINT”

(default: http://localhost:4317)

The endpoint to which traces and metrics will be sent.