Skip to content
ChinminaChinmina

Local development

Run Chinmina locally with Docker Compose to test changes against Buildkite and GitHub. The local stack requires credentials for both services.

Setting up your local environment

Section titled “Setting up your local environment”

Use direnv for environment configuration and mise to install and select the project toolchain. Install both tools and enable their shell integrations. Install Docker with Docker Compose to run the local integration stack.

Run mise install from the bridge repository root to install the tools defined in mise.toml. If you use a different toolkit, use this file as the authority for required tools and versions.

Setting up GitHub and Buildkite

Section titled “Setting up GitHub and Buildkite”

Refer to the “Getting Started” guide’s sections on Buildkite and GitHub for the creation of the Buildkite API key and the GitHub application.

Collect the configuration values as suggested.

Additionally, to run alongside Chinmina, there are several Buildkite Agent containers that are started. These will require the following environment variables to be forwarded in order to run correctly:

BUILDKITE_AGENT_TOKEN
Section titled “BUILDKITE_AGENT_TOKEN”

The agent token available from Buildkite when setting up a queue.

BUILDKITE_AGENT_TAGS
Section titled “BUILDKITE_AGENT_TAGS”

Used in testing only. These comma-separated, key-value pairs should be provided in order for the created agent containers to accept jobs.

Server configuration

Section titled “Server configuration”

  1. Create .envrc.private using the variable examples in the repository’s .envrc file. This file supplies local values without changing tracked configuration.

  2. Fill in the essential configuration values in .envrc.private.

  3. Run direnv allow to bring the updated configuration into the environment.

Running the server

Section titled “Running the server”

Run these commands from the bridge repository root:

  • just build to build the executables.
  • just test to run unit tests.
  • just docker-up --build to build the executables and container image, then start the integration stack.
  • just docker down to stop the integration stack.

The stack runs Chinmina workers behind Traefik, with a Buildkite agent, Valkey, and OpenObserve. The agent processes jobs from pipelines in your test organisation and authenticates to GitHub through Chinmina. View telemetry in OpenObserve at http://localhost:5080.

Run just to list available recipes, and just agent to format, lint, test, and build before committing.