Skip to content

feat!: add per-service roles for builds, environment and secrets - #1

Merged
sandrinodm merged 1 commit into
mainfrom
feat/roles
Nov 11, 2026
Merged

sandrinodm merged 1 commit into
mainfrom
feat/roles

Conversation

@sandrinodm

Copy link
Copy Markdown
Owner

A deploy.yaml describes one Compose stack, but builds, environment and secrets could only be set for the whole stack. A service's container variables had to be mapped by hand in Compose (FOO: ${FOO}), and every image had to come from one Dockerfile. This replaces targets with roles, keyed by Compose service name.

roles:
  web:
    build:
      target: server
    secrets:
      - SAMPLE_APP_API_TOKEN
  worker:
    build:
      dockerfile: docker/worker.Dockerfile
    environment:
      MY_API_BASE_URL: https://api.example.com/v1

What changes

  • Builds per role. build takes optional target, workingDirectory, dockerfile and context, each falling back to the top-level field. Without target the final stage is built. Roles can build from different Dockerfiles or repositories.
  • Images and tags. Images are named <name>-<role>:<tag>. Each Git repository is checked once, and its roles are tagged with its commit. --tag is repeatable: --tag <tag> for every role with build, --tag <role>=<tag> for one role. Tags are validated against Docker's tag rules.
  • Environment and secrets per service. A role's environment (literal values) and secrets (names from the stack's secret source) reach only that service's container. The top-level environment and secrets stay Compose interpolation inputs. The 1Password allowlist is variables plus every role secret.
  • Generated override. Compoza writes compoza.roles.yaml with each built service's image and each role's environment, and applies it as the last Compose file. Client and --local runs use a private temporary file. SSH runs merge it into the flat compose.yaml. The file holds ${NAME} references for secrets, never their values. --dry-run prints it in every mode.
  • Validation. Before anything is built, and in check and dry runs, a role is rejected if:
    • it is not a service in the selected Compose files
    • it sets a key the service already sets in Compose environment:. This follows !reset/!override, extends, YAML merge keys, and include: for client and --local runs.
    • a key is both in its environment and in its secrets
    • a secret name is reserved or clashes with the top-level environment
    • it takes secrets but the run has no secret source
  • Destinations and local can change a role's environment (merged per key) and secrets (replaced), but not its build.
  • .compoza.json records tags per role instead of one tag. The stack .env no longer holds image variables.

Breaking change

targets and the <TARGET>_IMAGE Compose variables are removed. A config with targets fails with a message naming the replacement. To migrate:

  1. Move each target to roles.<service>.build.target.
  2. Drop the image: ${<TARGET>_IMAGE} lines from your Compose files. A ${X_IMAGE:-fallback} default can stay.

Where a role name differs from its old target name, the image name changes, so earlier tags can't be reused with --tag. See "Migrating from 0.6.0" in docs/configuration.md.

Docs

The README, docs/ and both agent skills (.claude and .agents) are updated, including a new Roles section and a "Reusing images" section in the command reference. Older example names were made generic along the way.

Testing

  • pnpm check passes.
  • pnpm test: 518 passed, 2 skipped. The real-Compose runtime tests check that the merged model gets the override's image, a literal $ value and a resolved secret, with no secret written to the file.
  • pnpm pack plus pnpm test:package pass on the installed tarball.
  • Dry runs of a two-role sample app in client, --local and SSH modes print the expected override and build commands.

Not covered: no deploy against a real host was run.

Not in this PR

  • SSH status doesn't show the per-role tags yet. They are recorded in .compoza.json.
  • A destination or --local run can't remove a role.
  • --tag is accepted and ignored on stacks that build nothing.

🤖 Generated with Claude Code

Replace `targets` with `roles`, keyed by Compose service name. A role can
build an image (`build` with optional `target`, `workingDirectory`,
`dockerfile` and `context`, falling back to the top-level fields) and give
its container `environment` and `secrets`. Compoza applies these through a
generated Compose override, last in client, local and SSH runs, which never
holds secret values.

- Images are named `<name>-<role>:<tag>` and tagged per Git repository;
  `--tag` is repeatable and accepts `<role>=<tag>`.
- Roles are validated against the selected Compose files before anything is
  built, also by `check` and dry runs.
- The 1Password allowlist is `variables` plus every role secret.
- Destinations and `local` can change a role's environment and secrets.

BREAKING CHANGE: `targets` and the `<TARGET>_IMAGE` Compose variables are
removed. Move each target to `roles.<service>.build.target` and drop the
`image: ${<TARGET>_IMAGE}` lines; see "Migrating from 0.6.0" in
docs/configuration.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sandrinodm
sandrinodm merged commit dd73063 into main Nov 11, 2026
3 checks passed
@sandrinodm
sandrinodm deleted the feat/roles branch November 11, 2026 09:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant