Use the bundled green launcher in the deployment directory. It runs with
Babashka and resolves immutable package dependencies. Read
configuration.md before changing desired state.
Read github-deploy.md when adding continuous
deployment to an application's repository.
DMARC management is opt-in through smtp-dmarc-policy; see the configuration
reference for provider restrictions, reporting addresses, existing-record import,
and preserving a DNS record when removing management. Review any inherited
policy before setting an explicit sending-domain policy.
The package calls colors-compute for one host. The library owns provider selection, credentials, node state and encrypted SSH resources. ONCE owns the workflow scope and agent lifetime. Update its dependency to obtain provider support; do not add a compute template or provider branch to this package. ONCE owns application configuration, SMTP, DNS and GitHub publishing.
The package pins Basecamp ONCE to v0.3.3. A real create installs the
Linux amd64 or arm64 release binary with its pinned SHA-256 checksum, replacing
an existing binary when it differs. The managed background service disables
binary self-updates with ONCE_NO_SELF_UPDATE=1 and restarts when the binary or
service configuration changes. Application image auto_update and backups
remain available. Upgrading the binary does not recreate application containers;
v0.3.3's BASE_URL environment variable reaches an existing application only
when its container is recreated. The ONCE version is fixed by the package,
not a colors.yml setting.
Keep secrets in COLORS_PAR_* environment variables. Ask for variable names
and whether they are set, never their values. Do not read .envrc.private or
private keys. Never read generated .colors/ as source or edit it. Use one color
at a time for a deployment.
For initialization, preserve existing desired state and unrelated files. Copy
the bundled launcher, make it executable, and create or revise colors.yml
with non-secret settings. Ignore generated output and private environment files.
Validate with ./green build and ./green create --dry-run. These commands
contact no provider and do not prove credentials or live health.
A real create or delete needs user authorization. Existing authorization for
the task applies; do not ask again. Create validates, converges compute, then
SMTP, DNS, verification and application configuration. Compute ownership failure
stops subsequent resource creation. Delete loads recorded compute inventory,
withdraws published credentials and SSH configuration, removes DNS and SMTP,
then destroys compute and any provider registration. Encrypted SSH authority
is retained after compute deletion.
Keep compute-prevent-destroy: true in desired state; an authorized delete can
use COLORS_PAR_COMPUTE_PREVENT_DESTROY=false for that invocation.
This is a breaking, greenfield-only v2 implementation. Require
compute-api-version: 2, fresh identities and fresh state roots. Existing
deployments keep their pinned launchers and remain untouched. Do not add
migration, adoption or compatibility tooling. Supply and securely back up
COLORS_PAR_ONCE_SSH_PASSPHRASE. Never replace it to regenerate authority.
Use the launcher's ssh command for a scoped agent; a bare alias is insufficient.
Build renders separately under .colors/build/<profile>/.
Use ./green describe for recorded compute status and application inspection.
It reads compute through the library and requires a verified address before SSH.
For an application naming a GitHub repository, establish whether continuous
deployment is part of the user's request before adding its workflow. Confirm
the target repository matches owner/repo; the deployment repository may be a
different checkout. Follow the linked reference for the exact published values.
Create and build serialize the package-owned SSH alias stage before remote Ansible. A failed local ownership check stops application convergence; GitHub publication remains after remote convergence.
Compute command failures
Compute failures report the lifecycle stage, safe command prefix, resolved
executable and exit status when available, plus sanitized stderr. Missing
executables, process launch failures and timeouts have distinct explanations;
an unknown or older diagnostic keeps its authored message. For ssh, failures
before connecting begin with Cannot prepare SSH access. If tofu is missing,
make OpenTofu available on PATH and retry. From this repository, use
devenv shell -- green/green ssh. Standalone launchers need OpenTofu on
their calling shell's PATH.
When the compute library identifies Google invalid_rapt reauthentication,
the error names it and explains how to renew local user Application Default
Credentials with gcloud auth application-default login, or renew the configured
credentials through their own authentication method. ONCE does not launch login
or retry operations automatically. Structured output stays suppressed to protect
credentials and state; without a recognized diagnosis, the message explicitly
says the underlying cause could not be safely identified.