Development

Local development requires Go.

Source Checkout Runtime

Load .envrc when running Taxiway from the checkout:

source .envrc

It sets:

export TAXIWAY_CONTEXT=dev
export TAXIWAY_CONTEXT_ID="$(test -f "$PWD/.context-id" || uuidgen | tr '[:upper:]' '[:lower:]' | cut -c1-8 > "$PWD/.context-id"; cat "$PWD/.context-id")"
export TAXIWAY_AUTH_DIR="$PWD/.auth"
export TAXIWAY_OBSERVABILITY_DIR="$PWD/.observability"
export TAXIWAY_PROXY_DIR="$PWD/.proxy"
export TAXIWAY_RUNTIME_DIR="$PWD"
export TAXIWAY_LAB_STATE_DIR="$PWD/.lab-state"

These values make ./taxiway and go run ./cmd/taxiway use runtime assets from the checkout, keep lab state in ./.lab-state, and create an isolated dev runtime under ./.auth, ./.observability, and ./.proxy. The context id is generated once into ./.context-id so two local checkouts do not reuse the same Docker Compose project or gateway container, and so moving the checkout does not change the environment id.

Optional: use direnv to load .envrc automatically.

Build

go build -o ./taxiway ./cmd/taxiway
./taxiway version

The Makefile target builds all packages:

make build

Test

make test-unit
make lint

Docker-backed end-to-end tests require Docker and are intended for local, scheduled, or manually triggered validation:

make test-e2e

Use make test-e2e-only to run only end-to-end tests. Use make test-e2e-claude-code, make test-e2e-codex, or make test-e2e-gastown to run one orchestrator integration. Use the *-up variants before the *-phase-by-phase variants when debugging the scheduled orchestrator end-to-end sequence locally. Use make test-scripts to run shell script tests.

See Testing and Drivers.

Commit Messages

Release notes are generated by GoReleaser from commit messages. Use Conventional Commits for user-facing changes:

feat: add a new capability
fix: correct broken behavior
cleanup: simplify or remove obsolete behavior
docs: update documentation
test: add or update tests
refactor: change structure without changing behavior

GoReleaser groups feat: commits under Features, fix: commits under Fixes, and cleanup-style commits under Cleanup. Documentation, test, chore, style, refactor, merge, and revert commits are filtered from release notes by default.

Local Snapshot

To test the same packaging path as a release, build a GoReleaser snapshot and copy the platform binary back into the repository:

make snapshot

Snapshot builds are local-only and include the current commit in the version, for example 0.1.0-SNAPSHOT-2f1183a.

Local Completion

Generate completion for the local development binary:

make completion

You can also target a shell explicitly:

make completion-zsh
make completion-bash
make completion-fish

Release

See Release.