# Tremvok Every documentation page, concatenated. Canonical site: https://docs.magmamoose.com/tremvok/ --- # Action reference Source: docs/action-reference.md URL: https://docs.magmamoose.com/tremvok/action-reference/ Generated by `scripts/gen_action_reference.py`. Edit `action.yml`, not this page. For the task-shaped version, see [Setup](setup.md). ## Targets `target` is the only required input and it has no default. Everything else is optional, and every one of them is checked against the target you picked: an input that belongs to another target is a hard error naming both, before the checkout. | Target | What it does | | --- | --- | | `github-pages` | Build an MkDocs site strictly and publish it to GitHub Pages | | `cloudflare-docs` | Build an MkDocs site strictly and publish it to Workers Static Assets | | `s3-cloudfront` | Sync a built static site to S3, invalidate CloudFront | | `lambda-zip` | Publish a Lambda package to S3, update the function, move an alias | | `terragrunt` | Discover, plan and (on an approval) apply Terragrunt stacks | | `ansible` | Run a playbook over SSH, then prove it is idempotent | | `cloudflare-workers` | Deploy a Worker and its static assets with Wrangler | | `azure-functions-zip` | Publish a zip to an Azure Function App, then wait for it to answer | | `azure-apim-policy` | Publish policy documents to an API Management API, all or nothing | | `gitops-pr` | Open a deploy PR per kustomize overlay, the next when one merges | ## Inputs `MagmaMoose/tremvok@v2` takes 145 inputs. `target` is the only one that is required. | Input | Applies to | Default | Description | | --- | --- | --- | --- | | `target` | the selector | not set | The deployment target. One of: github-pages Build an MkDocs site strictly and publish it to GitHub Pages. s3-cloudfront Sync a built static site to S3 and invalidate CloudFront. lambda-zip Publish a Lambda package to S3, update the function, move an alias. terragrunt Discover, plan and (on an approval) apply Terragrunt stacks. ansible Run an Ansible playbook over SSH, then prove it is idempotent. cloudflare-workers Deploy a Worker and its static assets with Wrangler. cloudflare-docs Build an MkDocs site strictly and publish it to Cloudflare Workers Static Assets, behind the docs router. azure-functions-zip Publish a zip to an Azure Function App, then wait for it to answer. azure-apim-policy Publish policy documents to an existing Azure API Management API, putting the previous ones back if any is refused. gitops-pr Deploy a released image through kustomize overlays by pull request: one per overlay, the next opened when one merges. | | `mode` | all | `auto` | What this run should do. One of: auto (default) push to the default branch = deploy, pull\_request = preview, workflow\_dispatch = deploy (pinned to the default branch). deploy Publish to the environment. preview Publish somewhere disposable; production is untouched. rollback Re-publish a previously published version. | | `environment` | all | not set | Logical environment name, surfaced in notifications and the deployment record. Defaults to "production" (deploy) or "preview". | | `working-directory` | all | `.` | Directory to run in. Paths in the other inputs are relative to it. | | `checkout` | all | `true` | Run actions/checkout first. Set false if the caller already checked out. | | `dry-run` | all | `false` | Resolve, plan and report without changing anything. | | `aws-region` | `s3-cloudfront`, `lambda-zip`, `terragrunt` | not set | s3-cloudfront, lambda-zip, terragrunt: AWS region. Falls back to the AWS\_REGION environment variable. | | `aws-role-to-assume` | `s3-cloudfront`, `lambda-zip`, `terragrunt` | not set | s3-cloudfront, lambda-zip, terragrunt: IAM role ARN to assume with this run's GitHub OIDC token. Strongly preferred over stored keys: the credential expires in an hour and the role's trust policy decides which repository and ref may use it. Requires `permissions: id-token: write`. Leave empty to use credentials an earlier step already configured. | | `aws-role-duration-seconds` | `s3-cloudfront`, `lambda-zip`, `terragrunt` | `3600` | s3-cloudfront, lambda-zip, terragrunt: lifetime of the assumed-role session. | | `azure-client-id` | `terragrunt`, `azure-functions-zip`, `azure-apim-policy` | not set | terragrunt, azure-functions-zip, azure-apim-policy: client id of the Entra ID app registration this run signs in as, using the run's GitHub OIDC token. The Azure counterpart of `aws-role-to-assume`, and preferred over a stored publish profile or client secret for the same reasons: the session is minted per run and expires, and the app registration's federated credential decides which repository and which ref may mint one. A publish profile is a long-lived file carrying the deployment rights of the whole site, tied to nothing. Requires `permissions: id-token: write`. Leave empty to use a session an earlier step created. On `terragrunt` this is the PROVIDER's credential and has nothing to do with the state backend's, which `terragrunt-stack-env` carries. `provider "azurerm"` with no explicit auth falls through its default chain to the Azure CLI, so a run with a perfectly good ARM\_ACCESS\_KEY still fails at plan on a runner nobody signed in. | | `azure-tenant-id` | `terragrunt`, `azure-functions-zip`, `azure-apim-policy` | not set | terragrunt, azure-functions-zip, azure-apim-policy: Entra ID tenant the app registration lives in. Required whenever `azure-client-id` is set. | | `azure-subscription-id` | `terragrunt`, `azure-functions-zip`, `azure-apim-policy` | not set | terragrunt, azure-functions-zip, azure-apim-policy: subscription to select after login. Required whenever `azure-client-id` is set. On terragrunt it is the CLI default a stack inherits when its own provider block names no subscription. | | `gcp-workload-identity-provider` | `terragrunt` | not set | terragrunt: full resource name of the workload identity pool provider this run federates with, `projects//locations/global/workloadIdentityPools//providers/`. The Google counterpart of `aws-role-to-assume` and `azure-client-id`, and preferred over a downloaded service-account key for the same reasons: the credential is minted per run and expires, and the pool provider's attribute condition decides which repository and which ref may mint one. A service-account key is a long-lived file, valid until somebody deletes it, tied to nothing. Requires `permissions: id-token: write`. Leave empty to use credentials an earlier step created. On `terragrunt` this is the PROVIDER's credential. If your state lives in GCS the backend needs one too, and the same federated credentials serve both. | | `gcp-service-account` | `terragrunt` | not set | terragrunt: service account to impersonate after federating, `name@project.iam.gserviceaccount.com`. Empty (default) uses the federated identity directly, which works when the IAM bindings name the pool's `principalSet` rather than a service account. Set, the pool's principalSet needs `roles/iam.workloadIdentityUser` on it. | | `gcp-project-id` | `terragrunt` | not set | terragrunt: project exported as GOOGLE\_PROJECT and GOOGLE\_CLOUD\_PROJECT, for configurations that do not name one themselves. Optional. | | `pages-toolchain` | `github-pages`, `cloudflare-docs` | `auto` | github-pages, cloudflare-docs: how to install MkDocs, auto (default) \| uv \| pip. `auto` picks uv when a uv.lock is present, otherwise pip against `pages-requirements`. Detection exists so a caller does not have to declare per-repo what is already visible in the repo. | | `pages-dependency-group` | `github-pages`, `cloudflare-docs` | `docs` | github-pages, cloudflare-docs: uv dependency-group holding the docs tooling (uv toolchain only). | | `pages-requirements` | `github-pages`, `cloudflare-docs` | `docs/requirements.txt` | github-pages, cloudflare-docs: requirements file pinning the docs build (pip toolchain only). | | `pages-python-version` | `github-pages`, `cloudflare-docs` | `3.12` | github-pages, cloudflare-docs: Python version used to build the site. | | `pages-strict` | `github-pages`, `cloudflare-docs` | `true` | github-pages, cloudflare-docs: build with `--strict`, so a broken internal link or a nav entry pointing at a missing file fails rather than publishing a site with holes in it. | | `pages-site-dir` | `github-pages`, `cloudflare-docs` | `site` | github-pages, cloudflare-docs: directory the built site is written to. | | `pages-lint` | `github-pages`, `cloudflare-docs` | `true` | github-pages, cloudflare-docs: run the repo-shape checks (README budget and section order, licence agreement, link targets, Marketplace preflight, INHERIT clobber) before building. These are the rules nothing else covers; --strict already catches broken internal links. | | `pages-profile` | `github-pages`, `cloudflare-docs` | `auto` | github-pages, cloudflare-docs: repo profile for the shape checks, auto \| action \| service \| spec. | | `pages-readme-budget` | `github-pages`, `cloudflare-docs` | `0` | github-pages, cloudflare-docs: override the README line budget. 0 uses the profile default. | | `pages-markdownlint` | `github-pages`, `cloudflare-docs` | `true` | github-pages, cloudflare-docs: run markdownlint-cli2 over docs/ and README.md when a markdownlint config is present. Runs here rather than under MegaLinter because MegaLinter's `security` flavor carries no markdown linter, and MARKDOWN\_MARKDOWNLINT emits no SARIF, so it could never gate on net-new findings anyway. | | `pages-seo` | `github-pages`, `cloudflare-docs` | `true` | github-pages, cloudflare-docs: after the build, give every page its own meta description (from its first paragraph of prose; the home page keeps `site_description`), Open Graph and Twitter tags, a JSON-LD graph (WebSite, TechArticle, BreadcrumbList) and a markdown copy at `/index.md`, linked from the page and from llms.txt. Configured by `extra.seo` in mkdocs.yml (`locale`, `image`, `publisher`, `author`, `twitter`), every key optional. A tag a page already carries is never replaced or doubled, so a site with its own SEO hook keeps it. `false` skips the step. | | `pages-agent-ready` | `github-pages`, `cloudflare-docs` | `true` | github-pages, cloudflare-docs: after the build, make the site agent-ready. Writes an Agent Skills index at `/.well-known/agent-skills/index.json` with one skill that says what the site covers and how to read and cite it; loads WebMCP tools on every page (search the docs, read a page as markdown, list and open pages) from a same-origin script that does nothing in a browser without the API; and, for a public site served at the root of its host, writes an `/auth.md` saying the docs need no credentials, never for a site behind `cloudflare-docs-require-access`. Configured by `extra.agents` in mkdocs.yml (`mcp`, `skill`, `webmcp`, `auth_md`), every key optional. Anything the site already publishes of these is left alone. On github-pages the artifact then includes dot-directories, which is where the index lives. `false` skips the step. | | `build-git-credentials` | `github-pages`, `cloudflare-workers`, `cloudflare-docs` | not set | github-pages, cloudflare-workers, cloudflare-docs: credentials for the private git hosts the build fetches from, one ` :` per line. Empty (default) changes nothing. git.example.invalid x-access-token:<a short-lived token> A docs build that installs its theme with `pkg @ git+https:////.git@` needs that clone authenticated, and the clone is git's own, several processes below this action. Each line becomes one `url..insteadOf` rewrite carried in GIT\_CONFIG\_COUNT / GIT\_CONFIG\_KEY\_n / GIT\_CONFIG\_VALUE\_n for the rest of this job, so the requirements file keeps pinning the plain URL and stays reviewable. Never `git config --global`: a self-hosted runner is shared and long-lived, and a global rewrite would leave the token in `~/.gitconfig` for whatever runs on that machine next. The username is written out rather than assumed, because the forges disagree about it: `x-access-token` for a GitHub App token, `oauth2` for a GitLab one. The split is at the FIRST `:`, which is the safe way round — the username is the half that cannot contain one, so a token that does survives intact. Every token is masked on receipt and never echoed. A malformed line is refused by index and host, and the host is only quoted when it looks like one, because a bare token pasted as a line would otherwise be printed into an annotation as public as the repository. Blank lines and `#` comments are ignored. | | `artifact-path` | `s3-cloudfront`, `lambda-zip`, `cloudflare-workers`, `azure-functions-zip`, `azure-apim-policy` | not set | s3-cloudfront, lambda-zip, cloudflare-workers, azure-functions-zip, azure-apim-policy: the built artifact, a directory for s3-cloudfront, a .zip for lambda-zip and azure-functions-zip, and for azure-apim-policy a directory of policy documents: `api.xml` for the API scope and `.xml` for each operation. | | `s3-bucket` | `s3-cloudfront`, `lambda-zip` | not set | s3-cloudfront, lambda-zip: the bucket. For s3-cloudfront it serves the site; for lambda-zip it holds published artifacts. | | `s3-key-prefix` | `s3-cloudfront`, `lambda-zip` | not set | s3-cloudfront, lambda-zip: key prefix within the bucket. Previews are placed under `/previews//`. | | `s3-delete-orphans` | `s3-cloudfront` | `auto` | s3-cloudfront: pass --delete to `aws s3 sync`, removing bucket objects with no local counterpart. `auto` (default) means yes. | | `cloudfront-distribution-id` | `s3-cloudfront` | not set | s3-cloudfront: CloudFront distribution to invalidate after the sync. Empty means no invalidation, the CDN keeps serving the old objects until its TTL expires. | | `cloudfront-site-url` | `s3-cloudfront` | not set | s3-cloudfront: base URL the distribution serves, used to build the URL reported in notifications. | | `lambda-function-name` | `lambda-zip` | not set | lambda-zip: the function to update. | | `lambda-function-alias` | `lambda-zip` | `live` | lambda-zip: the alias moved to the new version in deploy mode. A preview publishes a version and does not move it. | | `lambda-version-label` | `lambda-zip` | not set | lambda-zip: names the immutable S3 key (`/.zip`). Defaults to the short commit SHA. | | `terragrunt-root` | `terragrunt` | `terraform` | terragrunt: directory the stacks live under. | | `terragrunt-exclude` | `terragrunt` | `modules _modules` | terragrunt: space-separated path segments that never hold a stack. `modules _modules` by default: a module has no state of its own, so a change to one plans the stacks beneath the nearest directory above it that has any. Add a stack that must only ever be applied by hand, one that rewrites a firewall wholesale, say, by its directory name, and the pipeline will not touch it: a change inside it plans nothing, not even the stacks beside it. An entry holding a `/` names a directory outright, such as `terraform/aws` or `network/prod`. Everything under it is applied by hand, however many stacks it holds, and a change there plans nothing either. | | `terragrunt-scope` | `terragrunt` | `auto` | terragrunt: `auto` (changed stacks on a PR/push, all on a schedule or dispatch), `all`, `changed`, or `direct`. Anything else fails the run. With `terragrunt-pull-request` set, `auto` means the stacks that pull request touches even on a manual run; `all` stays legal and means plan the whole estate, gate on that pull request's approval, comment on that pull request. `direct` is `changed` without the widening: only the stacks a changed path sits inside. A module or a shared `root.hcl` reaches none of them, and the run warns instead, because those are stacks nobody named. A `.md` file or a path outside `terragrunt-root` counts for nothing. Use it on the push of a repository where a merge applies with no reviewer. | | `terragrunt-stacks` | `terragrunt` | not set | terragrunt: stacks to run, as paths from the repository root, separated by spaces or newlines. Wins over `terragrunt-scope`. It is how `terragrunt-apply: force` applies named stacks by hand, and what `terragrunt-scope: direct` or `terragrunt-hold-destroys` stopped. A path that is not a stack, or that `terragrunt-exclude` keeps out, fails the run before anything is planned, and so does a value that is only whitespace. Empty (default) lets the scope decide. | | `terragrunt-pull-request` | `terragrunt` | not set | terragrunt: act on this pull request number instead of the one in the event payload. For a manual run that has to plan a named pull request. Its reviews are what the approval gate reads, its thread is where the plan comment goes, and its head commit is what the check run is published against, fetched from the API because a dispatch event carries no pull request. Empty (default) uses the event, which is every automatic run. Digits only. A manual run plans: dispatching a workflow is not approving a commit, so `terragrunt-apply: force` is what applies one by hand. Checking out the right tree stays yours: pass `ref: refs/pull//merge` to your own actions/checkout step and set `checkout: false` here, or the run plans whatever is on disk and says so. | | `terragrunt-apply` | `terragrunt` | `auto` | terragrunt: `auto` (apply on an independent approval), `never` (plan only), or `force`. Under `auto` the run must also be the event that asks for an apply: a pull-request review that is an approval, or a push with `terragrunt-apply-on-merge` on. A run that only finds an approval already standing plans and reports, because that approval was given for the commit it was given for and a commit pushed after it has not been reviewed. Re-approving applies. `force` skips the approval and is restricted to `terragrunt-apply-operators`. | | `terragrunt-apply-on-merge` | `terragrunt` | `false` | terragrunt: `true` lets a push to the default branch apply what was merged. `false` (the default) plans on a push and applies nothing, which is what this target has always done. A push event carries no pull request, so with this on the run asks the API which pull request the commit was merged from and reads that pull request's reviews: a merge that had an independent approval applies, a merge without one is reported and not applied. Off, none of that happens: no commit-to-pull-request lookup, no approval read, plan only. `without-approval` is for a repository with nobody to give that approval. A merge from a pull request into the pushed branch applies on its own say-so, and a pull request's check stops asking for an apply first. Nothing else applies: not a direct push, and not an approval on an open pull request. The merge is then the only review, so set `terragrunt-scope: direct` on the push and `terragrunt-hold-destroys` with it. Separate from `terragrunt-apply` on purpose. That input answers "who may authorise an apply?"; this one answers "should a merge commit apply at all?". Stacking the two questions into one enum makes both harder to read. | | `terragrunt-apply-operators` | `terragrunt` | not set | terragrunt: comma-separated GitHub logins allowed to force an apply by hand (`terragrunt-apply: force` on a manual run). Empty means nobody can, so the manual path fails closed. The normal path is an independent pull-request approval and needs nothing here. | | `terragrunt-hold-destroys` | `terragrunt` | `false` | terragrunt: `true` refuses to apply when any stack's saved plan destroys, replaces or forgets something, or cannot be read back, and fails the run so that somebody sees it. Nothing is applied, not even the stacks with nothing to destroy. If state moves after that check, a stack that still has changes fails rather than applying a plan nobody read, and the others carry on. `terragrunt-apply: force` goes past it, because that is somebody who read the plan. It cannot be combined with `terragrunt-rolling`. `false` (the default) applies what the plan says. | | `terragrunt-plan-pin` | `terragrunt` | not set | terragrunt: a file name, such as `plan.pin`, looked up in each stack's directory. It holds the plan summary the change to that stack is meant to produce, so a reviewer can see in the diff what a merge will do. Empty (default) turns it off. The first line that is not blank and not a `#` comment is the summary as tofu prints it, `Plan: 1 to import, 0 to add, 2 to change, 1 to destroy, 1 to forget.` or `No changes.`, with the trailing period optional. It is compared by its counts, so `0 to import` may be written out or left off. A plan that changes only outputs prints no summary, and its pin is `Plan: 0 to add, 0 to change, 0 to destroy.` A pin counts only for a stack the change reached directly: a file inside it changed, or `terragrunt-stacks` named it. A stack planned because a module or a shared file changed is not held to its pin, and no stack is on a scheduled run. The plan comment and the step summary say, per pinned stack, whether the plan matches. A plan that differs, or a plan or pin that cannot be read, fails the run, and a run that could apply applies nothing. A stack whose plan matches is past `terragrunt-hold-destroys`, because its pin declared what it destroys, and applies the plan its pin was checked against or nothing. `terragrunt-apply: force` goes past a pin as it goes past the hold, and the table still shows what differed. It cannot be combined with `terragrunt-rolling`. | | `terragrunt-stack-env` | `terragrunt` | not set | terragrunt: environment applied per stack, one ` KEY=VALUE` per line. The first matching line wins for a given KEY, so a specific pattern goes above the catch-all exactly as it would in a `case`. Blank lines and `#` comments are ignored. \*/prd/\*\|\*/prod/\* ARM\_ACCESS\_KEY=<the production state key> \* ARM\_ACCESS\_KEY=<the shared state key> For an estate whose production state lives in a separate account from the rest, which is a deliberate blast-radius boundary rather than an accident: one credential cannot reach both, and without this the only options are a job per credential class or a pipeline that fails on the first stack of the other kind. The values are secrets, so they are passed to each run with `env` rather than exported into the shell, and one stack's credential never reaches the next stack's run. A malformed line is refused by index, glob and KEY: nothing at or after the first `=` is ever printed, because the annotation it would appear in is as public as the repository. | | `terragrunt-rolling` | `terragrunt` | not set | terragrunt: stacks whose apply takes one unit at a time, `
[
...]` per line. The first matching line wins; blank lines and `#` comments are ignored. \*/k3s-cluster module.node Each address names a `for_each` or `count` block, and each of its instances is a unit: `module.node["worker-0"]` is one and `module.node["worker-1"]` another. Instances of two addresses that share a key are one unit, so `module.node aws_ebs_volume.data` rolls a node and its disk together. When the plan to be applied changes two or more units, the apply plans and applies each on its own with `-target`, in plan order, waits `terragrunt-rolling-pause` seconds before the next, and ends with a full plan that applies whatever no unit holds and proves every unit landed. A plan that changes one unit or none applies the saved plan as before. For a change that restarts what it touches. Resizing a cluster's VMs restarts each one, and one apply of the whole plan restarts every node at the same moment, which takes the cluster down. A unit whose targeted plan also changes another unit (tofu plans every instance of a resource that a target depends on) is refused before any of it is applied, so the run fails rather than restarting several units at once. | | `terragrunt-rolling-pause` | `terragrunt` | `300` | terragrunt: seconds to wait after a `terragrunt-rolling` unit is applied before the next one is planned, so the last one is back before another goes down. | | `terragrunt-check-name` | `terragrunt` | `Terragrunt apply` | terragrunt: name of the check run published against the head commit. Make it a required check to enforce apply-before-merge. | | `terragrunt-install` | `terragrunt` | `auto` | terragrunt: install pinned, checksum-verified tofu and terragrunt binaries before running, `auto` (default) installs only what is not already on PATH, `always` reinstalls, `never` uses whatever the runner provides. The download is cached per version pair, so a bump lands in a new directory and can never pick up a stale binary. | | `terragrunt-version` | `terragrunt` | `1.0.8` | terragrunt: the Terragrunt version to install and run. | | `terragrunt-tofu-version` | `terragrunt` | `1.12.1` | terragrunt: the OpenTofu version to install and run under Terragrunt. | | `terragrunt-plugin-cache` | `terragrunt` | `~/.terraform-plugin-cache` | terragrunt: directory to persist provider plugins in across stacks and runs, exported as TF\_PLUGIN\_CACHE\_DIR. The workspace is wiped on each checkout, so without it every stack re-downloads every provider, the single biggest cost in a multi-stack run. Empty disables the cache. | | `terragrunt-refresh` | `terragrunt` | `auto` | terragrunt: refresh state from the provider before planning, `auto` (default) skips the refresh on a pull request and keeps it everywhere else, `true` always refreshes, `false` never does. Config-versus-state is enough for a pull-request check; the scheduled drift run is the one that has to ask the provider. | | `terragrunt-plan-lock` | `terragrunt` | `auto` | terragrunt: whether a plan takes the state lock. `auto` (default) takes none on a `pull_request` run or on a `pull_request_review` that does not approve, the runs that never apply and that a newer push or review cancels, and takes it on every other run. `always` takes it on every plan, as before. An apply always locks. A plan writes nothing to state, and a plan cancelled while it holds the lock can be killed before it releases it. The lock is then stranded: every later run on that stack waits out its lock timeout and fails, until somebody force-unlocks it by hand. What no lock costs is that a plan reading state while another run applies can show a diff that apply is halfway through making. It is a pull-request comment, redone on the next push. | | `terragrunt-timeout` | `terragrunt` | `900` | terragrunt: seconds any one init, plan or apply may take before it is killed. 0 disables the timeout. A stalled provider call otherwise looks like a silent hang until the job limit. | | `terragrunt-preflight-urls` | `terragrunt` | not set | terragrunt: URLs to probe for reachability before the first plan, one per line. Empty (default) probes nothing. Terragrunt buffers plan output to a file, so a state backend or provider API the runner cannot reach is a silent wait until `terragrunt-timeout` rather than an error. One 8-second request per URL turns that into a red step naming the endpoint. `https://<your-state-backend-host>/?comp=list` `https://<your-provider-api-host>/api/versions` The rules worth knowing before you read a result: a code of 000 (DNS, connect, TLS or timeout) fails the run; any HTTP answer passes, 401 and 403 included, because an unauthenticated probe of a credentialed endpoint is supposed to be refused and being refused proves the endpoint is there. This proves reachability, not authorisation: a 403 does not mean the credential works. Blank lines and `#` comments are ignored. Put no credentials in these URLs; they are printed into the run log. A URL carrying userinfo is refused, and the refusal names the line by its index and shows the URL with the userinfo replaced rather than echoing the line. | | `terragrunt-credential-preflight` | `terragrunt` | `auto` | terragrunt: check that every cloud the discovered stacks name has a credential on this runner, before the first plan. `auto` (default) fails the run, `warn` annotates and plans anyway, `off` checks nothing. Exists because the credential a terragrunt run needs is not one credential. The state backend has its own (`terragrunt-stack-env`), and every `provider` block the stacks declare has another, from a different chain, that nothing in the workflow mentions. The failure that produces is the least readable in this action: state reads fine, init succeeds, and the plan dies inside a provider with `could not configure AzureCli Authorizer: … Please run 'az login'`, twenty stacks in a row, which reads as a broken runner rather than as a credential nobody wired. What it reads: the `provider ""` blocks in each discovered stack and in every parent directory up to `terragrunt-root`, so a `generate` block in a shared root.hcl counts. What it knows: azurerm/azuread/azapi, aws, google/google-beta, vcd. A provider it does not recognise is passed over in silence rather than guessed at. The state backend is deliberately not checked. A backend with no credential fails in `init`, immediately, naming the backend, which is already the good failure; and an ARM\_ACCESS\_KEY opens one storage account and cannot configure a provider, so counting it either way would be wrong. What it will NOT report: a provider block that configures its own authentication (`client_id`, `client_secret`, `use_oidc`, `use_msi`, `access_key`, `credentials`, `token`, `api_token` …), because that stack answers the question itself. That is the exemption that keeps this from being a check people turn off. This proves a credential is present, never that it is valid or that it can reach the subscription, project or account the stack names — the same distinction `terragrunt-preflight-urls` draws between reachable and authorised. | | `terragrunt-log-level` | `terragrunt` | not set | terragrunt: value for TF\_LOG when diagnosing a stuck provider call (debug, trace). Empty (default) leaves provider logging off; the log is written next to the plan and redacted before it is shown. | | `terragrunt-extra-args` | `terragrunt` | not set | terragrunt: extra flags appended to every plan and apply, split on whitespace. | | `ansible-playbook` | `ansible` | not set | ansible: path to the playbook to run, relative to working-directory. Required for this target. | | `ansible-inventory` | `ansible` | not set | ansible: inventory path or comma-separated host list passed to `-i`. Required for this target. | | `ansible-version` | `ansible` | `11.1.0` | ansible: exact version of the `ansible` PyPI distribution to install. Pinned rather than floating, because a collection that changes behaviour between releases is indistinguishable from a change you made. | | `ansible-python-version` | `ansible` | `3.12` | ansible: Python version the control node runs on. | | `ansible-galaxy-requirements` | `ansible` | not set | ansible: path to a galaxy requirements file installed with `ansible-galaxy install -r` before the run. Empty skips it. | | `ansible-limit` | `ansible` | not set | ansible: value for `--limit`, restricting the run to a subset of the inventory. | | `ansible-tags` | `ansible` | not set | ansible: value for `--tags`. | | `ansible-skip-tags` | `ansible` | not set | ansible: value for `--skip-tags`. | | `ansible-check` | `ansible` | `auto` | ansible: run in check mode, `auto` (default) means check mode on a pull request and a real run everywhere else, `true` forces check mode, `false` forces a real run. A pull request that silently reconfigured a fleet would be a surprising way to find out what a diff does. | | `ansible-diff` | `ansible` | `true` | ansible: pass `--diff`, so the log shows what each changed task changed. | | `ansible-extra-vars` | `ansible` | not set | ansible: value for `--extra-vars`. Accepts `key=value` pairs or JSON. | | `ansible-extra-args` | `ansible` | not set | ansible: extra flags appended to the playbook run, split on whitespace. | | `ansible-ssh-private-key` | `ansible` | not set | ansible: SSH private key used to reach the inventory. Pass a secret, never a literal. It is masked on receipt, written to a 0600 file under RUNNER\_TEMP, and removed when the step exits however it exits. | | `ansible-ssh-user` | `ansible` | not set | ansible: value for `--user`. Leave empty to let the inventory or ansible.cfg decide. | | `ansible-ssh-known-hosts` | `ansible` | not set | ansible: known\_hosts entries for the inventory, one per line. Empty means host-key checking is disabled for the run, which is a real downgrade, supply this for anything reachable from a network you do not control. | | `ansible-vault-password` | `ansible` | not set | ansible: vault password. Pass a secret. Masked on receipt, written to a 0600 file under RUNNER\_TEMP, removed when the step exits. | | `vault-addr` | `ansible` | not set | ansible: base URL of a HashiCorp Vault, e.g. `https://vault.example.com:8200`. Set it, with `vault-token`, to name secrets by Vault reference instead of passing them in. Only the fields you reference are read. | | `vault-token` | `ansible` | not set | ansible: Vault token the references are read with. Pass a secret. Needs read on the paths you reference and nothing else. | | `vault-namespace` | `ansible` | not set | ansible: Vault namespace (Enterprise). Empty is correct for open-source Vault. | | `ansible-vault-passthrough` | `ansible` | `false` | ansible: hand `VAULT_ADDR`, `VAULT_TOKEN` and `VAULT_NAMESPACE` to the ansible-playbook process, so the playbook can read its own secrets from the same HashiCorp Vault rather than having them copied into a second store that quietly stops being rotated. Needs `vault-addr` and `vault-token`; without both, nothing is passed. `false` by default, and the default removes them from the playbook's environment. A token scoped to the fields this action reads becomes a token every task, role and collection in the play can use, and widening a credential's blast radius should be a decision rather than something inherited by accident. Nothing to do with ansible-vault, the file-encryption tool; that is `ansible-vault-password`. | | `ansible-ssh-private-key-vault` | `ansible` | not set | ansible: Vault reference to the SSH private key, `#`, e.g. `secret/data/team/app#ssh_private_key`. The alternative to `ansible-ssh-private-key`, not a supplement: setting both fails. Use this where Vault is already the source of truth, so rotating there keeps rotating here and the key is not copied into a second store that quietly goes stale. | | `ansible-ssh-known-hosts-vault` | `ansible` | not set | ansible: Vault reference to the known\_hosts entries, `#`. The alternative to `ansible-ssh-known-hosts`. | | `ansible-vault-password-vault` | `ansible` | not set | ansible: Vault reference to the ansible-vault password, `#`. The alternative to `ansible-vault-password`. | | `ansible-verify-idempotence` | `ansible` | `true` | ansible: after a successful real run, run the playbook again in check mode and fail if any task would still change. A zero exit only proves the playbook ran; this is what proves it converged. Skipped automatically when the run itself was check mode. | | `cloudflare-api-token` | `cloudflare-workers`, `cloudflare-docs` | not set | cloudflare-workers, cloudflare-docs: API token Wrangler authenticates with. Pass a secret, never a literal. Mint it from Cloudflare's "Edit Cloudflare Workers" template rather than a hand-picked permission list, or the first deploy of a custom domain fails on a permission nobody thought to grant. | | `cloudflare-account-id` | `cloudflare-workers`, `cloudflare-docs` | not set | cloudflare-workers, cloudflare-docs: Cloudflare account id. Pass a secret. | | `cloudflare-config` | `cloudflare-workers`, `cloudflare-docs` | not set | cloudflare-workers, cloudflare-docs: path to the Wrangler config (wrangler.toml or wrangler.jsonc), passed as `--config`. Empty lets Wrangler find it, which is the normal case. The config owns the asset directory, routes, custom domains and 404 handling; the inputs here are overrides for the few things a workflow legitimately varies. | | `cloudflare-worker-name` | `cloudflare-workers`, `cloudflare-docs` | not set | cloudflare-workers, cloudflare-docs: overrides the `name` in the Wrangler config, passed as `--name`. | | `cloudflare-env` | `cloudflare-workers` | not set | cloudflare-workers: Wrangler environment, passed as `--env`. This selects a config block, which is not the same thing as the shared `environment` input: that one is a label for notifications and the deployment record. | | `cloudflare-main` | `cloudflare-workers` | not set | cloudflare-workers: entry point for a Worker that runs code, passed as Wrangler's positional path argument. Leave empty for an assets-only Worker, which is the shape that serves static files straight from the edge with no cold start and no code in the request path. | | `cloudflare-build-command` | `cloudflare-workers` | not set | cloudflare-workers: command run in working-directory before Wrangler, for a Worker that needs bundling. Empty skips it. | | `cloudflare-compatibility-date` | `cloudflare-workers` | not set | cloudflare-workers: overrides the config, passed as `--compatibility-date`. | | `cloudflare-minify` | `cloudflare-workers` | `false` | cloudflare-workers: pass `--minify`. Applies to Worker code, not to static assets. | | `cloudflare-vars` | `cloudflare-workers` | not set | cloudflare-workers: plain (NOT secret) variables, one `KEY=VALUE` per line, each passed as `--var`. Wrangler deletes vars not present in the config unless `--keep-vars` is set, so anything set in the dashboard belongs in the config instead. | | `cloudflare-wrangler-version` | `cloudflare-workers`, `cloudflare-docs` | `4.114.0` | cloudflare-workers, cloudflare-docs: exact Wrangler version to run. Pinned, because the tool that publishes to production is not a floating dependency. | | `cloudflare-node-version` | `cloudflare-workers`, `cloudflare-docs` | `24` | cloudflare-workers, cloudflare-docs: Node version Wrangler runs on. Wrangler 4 declares `engines.node >= 22`, and on 20 it installs cleanly and then refuses to run, so this does not default to whatever the runner happens to ship. | | `cloudflare-docs-host` | `cloudflare-docs` | not set | cloudflare-docs: hostname the docs router serves, e.g. `docs.magmamoose.com`. The site Worker itself has no hostname — it is reachable only through the router's service binding — so this is the address the Access check and the reported URL are about. Required when `cloudflare-docs-require-access` is on. | | `cloudflare-docs-path` | `cloudflare-docs` | not set | cloudflare-docs: path segment this repository's site is served under on `cloudflare-docs-host`. Empty (default) uses the repository name, which is what the router dispatches on, so overriding it is for a repo whose site is mounted elsewhere. | | `cloudflare-docs-require-access` | `cloudflare-docs` | `false` | cloudflare-docs: refuse to publish unless a Cloudflare Access application actually covers `/`. This is enforcement, not convention: "the site is behind Access" is otherwise a belief nothing checks, and the deploy is the one moment something can ask Cloudflare and refuse. Needs the `Access: Apps` READ permission on `cloudflare-api-token` — the "Edit Cloudflare Workers" template does not include it, and a 403 is treated as "could not tell", never as "nothing covers it". | | `cloudflare-docs-index` | `cloudflare-docs` | `true` | cloudflare-docs: emit the docs corpus from the build: `llms.txt` and `llms-full.txt` written into the site before it is published, and a search index of every page for the documentation MCP servers. One pass over the markdown that was just rendered; no credentials and no network. Publishing the index is a separate opt-in, `cloudflare-docs-index-bucket`. | | `cloudflare-docs-index-bucket` | `cloudflare-docs` | not set | cloudflare-docs: R2 bucket the index is published to, as `index/.json`. Empty (default) writes llms.txt into the site and uploads no index. Only a deploy writes it, and only after the site itself deployed: a pull request would otherwise overwrite the shared corpus with an unmerged branch. Needs R2 object write on `cloudflare-api-token`, which the "Edit Cloudflare Workers" template does not include. | | `cloudflare-docs-capability-file` | `cloudflare-docs` | `capability.json` | cloudflare-docs: this repository's capability declaration, published to `capability/.json` in `cloudflare-docs-index-bucket`. Empty disables it; the default names a file most repositories do not have, and absent is the normal case — most repositories are not house tools. Present, it is validated against `https://mcp.magmamoose.com/schema/capability.schema.json` on every run, including a pull request, and a declaration that does not satisfy it FAILS THE RUN: the MCP reads a malformed document as private and reports it as unreadable, counted and never named, which is the one state invisible from the publishing side. `private` is republished from the repository's own visibility on the same fail-closed rule as the docs index, and `commit` and `generated` are stamped from the run. | | `cloudflare-extra-args` | `cloudflare-workers` | not set | cloudflare-workers: extra flags appended to the Wrangler invocation, split on whitespace. | | `cloudflare-verify-config` | `cloudflare-workers` | `true` | cloudflare-workers: before publishing, run `wrangler deploy --dry-run` and refuse to publish if Wrangler reports configuration it will not apply: an unexpected field (a misspelled `[[r2_bucket]]` is only a warning, and the Worker deploys with no bucket), or a top-level binding an `--env` deploy does not inherit. A binding is only real if Wrangler prints it. Costs one extra bundle per run. | | `functions-app-name` | `azure-functions-zip` | not set | azure-functions-zip: the Function App to publish to. Required for this target. | | `functions-resource-group` | `azure-functions-zip` | not set | azure-functions-zip: resource group the Function App lives in. Required for this target. | | `functions-slot` | `azure-functions-zip` | not set | azure-functions-zip: deployment slot to publish to instead of production. Empty (default) publishes to the app itself. This is also what a preview has to use. A pull request must not publish onto the routes production serves, and a slot is Azure's only destination that does not — but a Linux Consumption plan HAS NO SLOTS. So on Consumption a preview is refused and says why, rather than quietly shipping a branch to production. On Premium or Dedicated, set this and previews go to the slot. | | `functions-ready-attempts` | `azure-functions-zip` | `30` | azure-functions-zip: how many times to ask the app for an answer after publishing, before calling the deploy dead. Any HTTP status passes, including a 404 at the root, which is what a Function App whose only trigger is at `/api/` normally returns. Only a connection failure and a 503 count as "not yet". The default is generous on purpose: a freshly created Consumption app 503s from both the site and its SCM endpoint until content is first published, so a FIRST deploy has to retry through that rather than fail on it. | | `functions-ready-delay` | `azure-functions-zip` | `10` | azure-functions-zip: seconds between readiness attempts. With the default attempts, that is a five-minute ceiling on a cold first publish. | | `apim-service-name` | `azure-apim-policy` | not set | azure-apim-policy: the API Management instance to publish to. Required for this target. | | `apim-resource-group` | `azure-apim-policy` | not set | azure-apim-policy: resource group the instance lives in. Required for this target. | | `apim-api-id` | `azure-apim-policy` | not set | azure-apim-policy: the API the documents are published to, by its id (the name in its resource id, not its display name). Required for this target. The API and its operations must already exist. This target publishes behaviour into them, the way azure-functions-zip publishes code into an existing Function App, and a document named after an operation the API does not have is refused before anything is published. | | `apim-policy-format` | `azure-apim-policy` | `rawxml` | azure-apim-policy: how the documents are written. `rawxml` (default) is what the portal's editor shows: policy expressions unescaped, `@(context.Request.Headers.GetValueOrDefault("x", ""))` as it reads. `xml` is strict XML, with every quote and angle bracket inside an expression entity-escaped. Mixing them up fails at publish, when API Management compiles the expressions. | | `gitops-suite-images` | `gitops-pr` | not set | gitops-pr: opt-in suite promotion, JSON image repository to tag map. Each app keeps its own version; one stable PR per environment accumulates pending changes. | | `gitops-suite-overlay` | `gitops-pr` | not set | gitops-pr: exact overlay directory for suite promotion. Requires gitops-suite-images and gitops-base. | | `gitops-suite-repositories` | `gitops-pr` | not set | gitops-pr: optional JSON image repository to owner/repository map for current selected release links in the suite PR. | | `gitops-suite-allowed-actors` | `gitops-pr` | not set | gitops-pr: comma or whitespace separated GitHub logins allowed to dispatch manual suite changes. Both original and rerun actors must match; empty denies manual changes. | | `gitops-suite-allow-downgrade` | `gitops-pr` | `false` | gitops-pr: permit a suite downgrade only on an authorized manual dispatch. | | `gitops-overlays` | `gitops-pr` | not set | gitops-pr: the kustomize overlay directories a release is deployed through, in promotion order, separated by whitespace (one per line reads best). Required for this target. k8s/overlays/acc k8s/overlays/prd A release opens a deploy PR for the first; merging it opens the one for the second, and so on. An overlay is named by its last path segment (`acc`), which is part of the deploy PR branch (`deploy/acc/v1.2.3`), so the names must be unique. Each overlay's kustomization lists the images in `images:` with a `newTag`, and the image automation that used to write it must be gone, or the two fight over the same line. | | `gitops-images` | `gitops-pr` | not set | gitops-pr: the image repositories a deploy moves, as the overlays name them (`name`, or `newName` where an entry has one), without a tag, separated by whitespace. Required for this target. Every one moves to the release's tag; an overlay that lists none of them is an error, one that lists some of them gets a warning for the rest. | | `gitops-tag` | `gitops-pr` | not set | gitops-pr: deploy this tag to the first overlay instead of the release event's. For a deploy by hand from `workflow_dispatch`, or to re-open one. Empty (the default) takes the tag from the published release, or promotes what a merged deploy PR moved. | | `gitops-base` | `gitops-pr` | not set | gitops-pr: the branch the overlays are read from and deploy PRs target: the one the cluster's controller watches. Empty (the default) is the pushed branch on a push, and the repository's default branch otherwise. Set it when those differ, e.g. `master` in a repository whose default branch is `dev`. | | `gitops-branch-prefix` | `gitops-pr` | `deploy` | gitops-pr: prefix for deploy PR branches, `//`. A merged pull request is recognised as a deploy PR by it, so change it only with the open ones merged or closed. | | `gitops-prereleases` | `gitops-pr` | `false` | gitops-pr: deploy prerelease GitHub Releases too. Off by default: only a stable release opens a deploy PR. | | `gitops-prereleases-until` | `gitops-pr` | not set | gitops-pr: the overlay a prerelease stops at, by name (`acc`) or path, for release candidates. Empty (the default) sends a prerelease through every overlay like a stable release, when `gitops-prereleases` is on. Set, a prerelease's deploy PRs stop at this overlay. A stable release whose own prerelease this overlay already runs (v1.4.0 while acc runs v1.4.0-rc.2) starts at the overlay after it: the signed-off candidate reaches production under its stable tag, without a second deploy to acceptance. A stable release with no candidate running there starts at the first overlay, as usual, so production only ever gets what acceptance ran. It cannot be the last overlay. | | `gitops-preview-labels` | `gitops-pr` | not set | gitops-pr: labels that each claim one preview environment, one per line, for a controller that deploys the open pull request carrying a label: Flux Operator's `GitHubPullRequest` input provider with `filter.labels` and `filter.limit: 1`. Empty (the default) leaves labels alone. deploy/preview-1 deploy/preview-2 On a pull request run, the first pull request to take a label holds it, and one that takes it later loses the label again, with a comment naming the holder. Taking the label off, or closing the pull request, releases it; closing also takes the label off, so a reopened pull request does not take the environment back. Nothing is deployed: the controller does that. Run it on `pull_request` `labeled`, `unlabeled` and `closed`, with a concurrency group per label. | | `gitops-preview-urls` | `gitops-pr` | not set | gitops-pr: each preview environment's URL, as a JSON object from a label in `gitops-preview-labels` to its URL, for the comment on the pull request that holds it. Optional. | | `verify-url` | all | not set | Post-deploy: the URL that must answer. Empty skips verification. Catches the deploy that uploaded but did not bind, the one failure that otherwise looks green. | | `verify-header` | all | not set | Post-deploy: a response header that must be present on `verify-url` (e.g. content-security-policy). | | `verify-header-match` | all | not set | Post-deploy: an extended regex the `verify-header` value must match. | | `verify-method` | all | `GET` | Post-deploy: HTTP method used to request `verify-url`. `GET` by default. Set it where a GET cannot verify the endpoint at all. A webhook receiver binds POST and nothing else, so a GET reaches no function and the platform answers 404 — which is also what an empty package returns, leaving the check unable to tell a working deploy from a broken one. `verify-method: POST` with `verify-status: 401` asserts that the function is bound and that its signature check refuses an unsigned request, which is the thing worth knowing. The method survives a redirect: curl otherwise downgrades a redirected POST to a GET, which would quietly turn the assertion into a different one. | | `verify-status` | all | `200` | Post-deploy: expected HTTP status from `verify-url`. | | `verify-attempts` | all | `6` | Post-deploy: how many times to try `verify-url` before failing. | | `verify-delay` | all | `10` | Post-deploy: seconds between verification attempts. | | `notify` | all | `always` | `always` (default), `on-success`, or `on-failure`. Applies to the webhook sinks. | | `pr-comment` | all | `auto` | Sticky pull-request comment. `auto` (default) means on for preview mode and for the terragrunt target. | | `slack-webhook` | all | not set | Slack incoming-webhook URL. Empty means the sink is off. Never fails the deploy. | | `teams-webhook` | all | not set | Microsoft Teams incoming-webhook URL. Empty means the sink is off. Never fails the deploy. | | `api-url` | all | not set | Base URL of a Tremvok API to record this deployment with. Authenticates with a GitHub OIDC token, so the repository stores no credential. Empty means no record is kept. | | `api-audience` | all | `tremvok` | OIDC audience the Tremvok API expects. | | `auth-token` | all | `${{ github.token }}` | Token used for the pull-request comment and the check run. Needs `pull-requests: write` and, for the terragrunt target, `checks: write`. For gitops-pr it also opens the deploy PRs, so it needs `contents: write`, and it must be an App token: a pull request opened with GITHUB\_TOKEN starts no workflow, so its required checks never report. Preview claims (`gitops-preview-labels`) need only `pull-requests: write`, and GITHUB\_TOKEN will do. | | `allow-fork-preview` | all | `false` | Let a fork pull request attempt a deploy. Off by default and almost always wrong: a fork cannot read secrets, so this only converts an honest skip into an auth error. | | `allow-dispatch-from-any-ref` | all | `false` | Let a manual run deploy from a branch other than the default one. Off by default, publishing a topic branch to production usually is not what "Run workflow" meant. | ## Outputs | Output | Description | | --- | --- | | `target` | The deployment target this run used. | | `mode` | The resolved mode: deploy, preview or rollback. | | `environment` | The resolved environment name. | | `url` | URL of what was deployed, when the target produces one. For gitops-pr, the deploy PR this run opened or refreshed. | | `deployed` | true when something was actually deployed (false for a skip). | | `verified` | true when post-deploy verification ran and passed. | | `skipped` | true when the run skipped (fork pull request, or no credential). | | `skip-reason` | Why it skipped, in a sentence. | | `record-id` | Identifier returned by the Tremvok API, when api-url is set. | | `site-dir` | github-pages: absolute path to the built site. | | `pages-toolchain` | github-pages: the toolchain actually used, uv or pip. | | `version-id` | lambda-zip, cloudflare-workers, azure-functions-zip, azure-apim-policy, gitops-pr: the published version. A Lambda version number, a Worker Version ID, the package sha256, the sha256 of the policy set — Azure exposes no per-deploy content hash of its own — or the image tag a deploy PR moves to. | | `stacks` | terragrunt: how many stacks this run discovered. | | `plan-changes` | terragrunt: how many of those stacks planned with a diff. | | `applied` | terragrunt: true when this run applied, false when it only planned. | | `changed-tasks` | ansible: how many tasks reported changed on the real run. | | `idempotent` | ansible: true when the second check-mode run found nothing left to change. | | `gitops-result` | gitops-pr: what the run did: `created`, `refreshed`, `unchanged` (the overlay already runs the tag), `skipped` (it runs a newer one, or a newer deploy PR is open) or `planned` (dry run). Empty when there was nothing to deploy. | | `gitops-preview-result` | gitops-pr: with gitops-preview-labels, what a pull request run did with its claim: `claimed` (it holds the label), `refused` (another pull request holds it, so the label came off), `released` (it held the label and let it go) or `ignored` (the event changed no claim of its own). Empty on any other run. | ## Required permissions Declared by the **caller**, because a composite action cannot declare `permissions:`. Only what the target actually uses: ### `target: github-pages` ```yaml permissions: contents: read # checkout pages: write # actions/deploy-pages, in the caller's own job id-token: write # actions/deploy-pages ``` ### `target: s3-cloudfront` ```yaml permissions: contents: read # checkout id-token: write # assume the deploy role by OIDC pull-requests: write # the sticky preview comment ``` ### `target: lambda-zip` ```yaml permissions: contents: read # checkout id-token: write # assume the deploy role by OIDC pull-requests: write # the sticky preview comment ``` ### `target: terragrunt` ```yaml permissions: contents: read # checkout id-token: write # assume the deploy role by OIDC pull-requests: write # the rolling plan comment checks: write # the check run that makes apply-before-merge enforceable ``` ### `target: ansible` ```yaml permissions: contents: read # checkout pull-requests: write # the sticky run comment ``` ### `target: cloudflare-workers` ```yaml permissions: contents: read # checkout pull-requests: write # the sticky preview comment ``` ### `target: cloudflare-docs` ```yaml permissions: contents: read # checkout pull-requests: write # the sticky preview comment ``` ### `target: azure-functions-zip` ```yaml permissions: contents: read # checkout id-token: write # sign in to Azure by OIDC pull-requests: write # the sticky preview comment ``` ### `target: azure-apim-policy` ```yaml permissions: contents: read # checkout id-token: write # sign in to Azure by OIDC pull-requests: write # the sticky preview comment ``` ### `target: gitops-pr` ```yaml permissions: contents: read # deploys: an App token in auth-token opens the deploy PRs pull-requests: write # preview claims with GITHUB_TOKEN: the labels and comments ``` `target: github-pages` is the one target the action cannot finish on its own: `actions/deploy-pages` needs `pages: write` and the `github-pages` environment, and a composite action can declare neither. The action builds and stages the artifact; the caller's job runs `actions/deploy-pages`. Every other target completes inside the action. --- # Agent readiness Source: docs/agent-readiness.md URL: https://docs.magmamoose.com/tremvok/agent-readiness/ A docs site built by either docs target is readable and usable by AI agents without any setup: the build writes what an agent looks for into the site it publishes. A few things live outside the site (DNS records, zone rules, an OAuth server), and those are the owner's to add. This page says which is which. The yardstick is [isitagentready.com](https://isitagentready.com/), whose check names are used below, and a scan says where a host stands: ```bash curl -s -X POST https://isitagentready.com/api/scan \ -H 'content-type: application/json' -d '{"url":"https://docs.example.com"}' | jq .checks ``` ## What every build writes Three steps after `mkdocs build`, on `github-pages` and `cloudflare-docs` alike. None needs credentials or network, each is on by default, and each leaves alone whatever the site already publishes of its own. | Check | What the build writes | Step (input) | |---|---|---| | `markdownNegotiation` (half of it) | every page's markdown at `/index.md`, linked from the page | page metadata (`pages-seo`) | | llms.txt, llms-full.txt | `/llms.txt` and `/llms-full.txt` (`cloudflare-docs` only) | the corpus (`cloudflare-docs-index`) | | `agentSkills` | `/.well-known/agent-skills/index.json` and one `SKILL.md` | agent readiness (`pages-agent-ready`) | | `webMcp` | WebMCP tools on every page, from `assets/javascripts/webmcp.js` | agent readiness (`pages-agent-ready`) | | `authMd` | `/auth.md`, for a site at the root of its host | agent readiness (`pages-agent-ready`) | ### The skill `/.well-known/agent-skills/index.json` follows the [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) (v0.2.0) and lists one skill, `/.well-known/agent-skills//SKILL.md`, which tells an agent: - what the site covers: `site_description` and the top of the nav, a line per section with the pages in it; - how to read it: `llms.txt`, `llms-full.txt`, the markdown copy of each page, asking a page URL for `Accept: text/markdown`, the MCP server when one is configured, and the WebMCP tools; - how to cite it: the page URL, never the markdown copy's. Each of those is mentioned only when the build actually wrote it. `github-pages` writes no `llms.txt`, and `pages-seo: false` writes no markdown copies, so the skill does not send an agent to either. The index carries the SHA-256 of the exact bytes written, which a client checks before it loads the skill. The name is `site_name` lowercased and hyphenated (`Caleb Sargeant's Docs` becomes `caleb-sargeants-docs`), and the skill's URL in the index is path-absolute at the address the site is served from (`//.well-known/...` behind a router). MkDocs leaves dot-directories out of the build, which is why the step writes these into the built site rather than reading them from `docs/`. On `github-pages` the Pages artifact then includes dot-directories, since `actions/upload-pages-artifact` drops them otherwise and the index would never be published. ### WebMCP Every page loads one same-origin script, deferred, which registers four tools with the browser's model context ([WebMCP](https://webmachinelearning.github.io/webmcp/)): | Tool | What it does | |---|---| | `search_docs` | searches MkDocs' own search index (or `llms.txt` without one), best match first | | `read_page` | returns a page of the site as markdown, the open page by default | | `list_pages` | lists every page with its title, URL and markdown URL | | `open_page` | navigates the tab to another page of the site | The script uses `document.modelContext` and `navigator.modelContext`, whichever the browser has, and never defines either. It registers on load rather than on an event, because a scanner reads the registrations a few seconds after navigation. It fetches nothing until a tool runs, and nothing outside the site: every URL a tool is handed is checked against the site's root, which the script finds from its own address, so it works at `/` and at `//` alike. A CSP of `script-src 'self'` and `connect-src 'self'` admits all of it. In a browser without WebMCP it does nothing at all. ### auth.md Written only when the site is served at the root of its host (`site_url` with a path of `/`), because `/auth.md` speaks for the host, and never for a site behind Cloudflare Access (`cloudflare-docs-require-access`), which nobody reads without signing in. A GitHub Pages site with access control turns it off with `auth_md: false`. It says what is true of a public static site: reading needs no account, there is nothing to register for, and no credential is sent. When an MCP server is configured it names it and points at the server's own OAuth protected-resource metadata (RFC 9728) as the authority on its access, rather than restating it. That is what keeps it from contradicting a real one. A host that routes `/auth.md` to an MCP Worker (see [OAuth](#oauth-for-an-mcp-server-on-the-docs-host) below) never serves this file at that path, because the route answers first; the copy only surfaces if the route goes, and it is true either way. ### Configuration Everything is optional, under `extra.agents` in `mkdocs.yml`. `extra` is a dict, so a shared base can set it once through `INHERIT`: ```yaml extra: agents: mcp: https://mcp.example.com/ # named in the skill and in auth.md skill: # or `false`: no skill name: example-docs # default: site_name, lowercased and hyphenated description: ... # default: from site_name and site_description webmcp: true # false: no WebMCP script auth_md: auto # auto: only at the root of a host; true; false ``` `pages-agent-ready: false` turns the whole step off, and the Pages artifact goes back to leaving dot-directories out. A site keeps what it already publishes: its own `/.well-known/agent-skills/`, whole; its own `webmcp.js` at that path, with no page pointed at a second one; a page that already loads a `webmcp.js`; and its own `auth.md`. The same rules make a second run change nothing. ## What the docs router adds On a host shared by path, like `docs.magmamoose.com`, a client only ever looks at the host's root, and each site's files sit under `//`. The router in `workers/docs-router/` fills the gap: - **`/.well-known/agent-skills/index.json`** lists a skill for the host itself, then every public site's skills, read from each site's own index over the service binding, re-addressed from the root and cached like the `llms.txt` summaries. Sites in `PRIVATE_SITES` are never read. - **WebMCP on the landing page**: `list_docs_sites`, `search_docs` across every site's `llms.txt`, `read_page` and `open_site`, from `/webmcp.js`, which the page's CSP admits as `'self'`. Only while `LANDING_REDIRECT` is blank: once `/` redirects, a browser (a scanner's included) reads the tools of the page it lands on, which then needs its own. - **Markdown negotiation**: a page asked for with `Accept: text/markdown` is answered with its `index.md`, falling back to the HTML page where a site has none. - CORS on every skills file, which the RFC asks for when browser-based clients read them. A site behind the router gets no `auth.md` of its own: `/auth.md` on the host is the host's. ## What only the owner can do ### Markdown negotiation on a host of its own The build writes the markdown; answering `Accept: text/markdown` with it happens before the request reaches the site. The router does this for its host. A site on a host of its own needs a URL rewrite Transform Rule on the zone (**Rules → Transform Rules → URL Rewrite**), which is what `docs.calebsargeant.com` uses: - **When incoming requests match**: ```text (http.host eq "docs.example.com" and ends_with(http.request.uri.path, "/") and starts_with(http.request.headers["accept"][0], "text/markdown")) ``` - **Path → Rewrite to → Dynamic**: `concat(http.request.uri.path, "index.md")` The first media range has to be `text/markdown`, the rule the router follows too, so a browser never gets markdown by accident. Unlike the router, a zone rule cannot fall back to the HTML page, so every page needs its markdown copy, which the page metadata step writes for every page the build emits. On `cloudflare-docs` add `Vary: Accept` and `Content-Type: text/markdown; charset=utf-8` in the site's `_headers`. GitHub Pages can neither rewrite nor set a header, so a site there needs a proxy in front of it (a Cloudflare zone does), or does without. ### DNS-AID records The `dnsAid` check looks for [DNS for AI Discovery](https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/) records: SVCB records under the host's `_agents` name, signed with DNSSEC. A docs host whose MCP server lives elsewhere publishes, for example: ```text _index._agents.docs.example.com. 3600 IN SVCB 1 docs.example.com. alpn="h2,h3" port=443 _mcp._agents.docs.example.com. 3600 IN SVCB 1 mcp.example.com. alpn="mcp" port=443 mandatory=alpn,port ``` `_index` is the draft's well-known entry point, pointing at the host that describes what is there; the second names the MCP endpoint, with the agent protocol in `alpn`. The draft's own parameters (`cap`, `well-known` and the rest) have no registered code points yet, so use numeric `keyNNNNN` names for them until they do. The zone needs DNSSEC switched on, or a validating resolver never returns the records as authenticated. The scanner's [dns-aid skill](https://isitagentready.com/.well-known/agent-skills/dns-aid/SKILL.md) has the checks it runs. ### OAuth for an MCP server on the docs host `oauthDiscovery`, `oauthProtectedResource` and a real `authMd` describe a server that issues tokens, and a static site issues none. Serve them from the MCP server's own Worker, with Workers routes on the zone for these paths of the docs host: ```text docs.example.com/mcp* docs.example.com/auth.md docs.example.com/oauth/* docs.example.com/agent/* docs.example.com/.well-known/oauth-authorization-server* docs.example.com/.well-known/oauth-protected-resource* docs.example.com/.well-known/openid-configuration ``` A route is more specific than the site's own `docs.example.com/*` route, and takes precedence over a Custom Domain such as the router's, so these paths reach the MCP Worker and everything else still reaches the docs. The site's own `auth.md` stays in the build, shadowed at `/auth.md` by the route, which is why it says nothing about the server that could go stale. ### Not covered `a2aAgentCard` describes an agent that speaks the A2A protocol. A docs host runs none, so there is no honest card to publish. --- # API reference Source: docs/api.md URL: https://docs.magmamoose.com/tremvok/api/ Optional. Leave the action's `api-url` empty and nothing here is called. Base URL: whatever `terraform output api_url` reports, an API Gateway HTTP API endpoint in production, a Lambda Function URL under LocalStack. ## Authentication A **GitHub Actions OIDC token**, and nothing else. There is no API key to mint, store, rotate or leak. ```http authorization: Bearer ``` The action does this for you (`record-deployment.sh`); a workflow only needs `permissions: id-token: write`. Verification, in order: 1. `alg` must be `RS256`. `none` and the HMAC algorithms are rejected before any signature work With HS256, anyone holding the public key can sign their own token with it. 2. The signature must verify against the issuer's JWKS (fetched and cached per execution environment, refetched on an unknown `kid` so key rotation is a non-event). 3. `iss` must be a configured issuer, `aud` must match, `exp`/`nbf` must be current within 60 seconds of clock skew. 4. `repository_owner` must be in `allowed_owners`, and must agree with `repository`. **Step 4 is the one that matters.** GitHub issues an OIDC token to every repository on github.com, so steps 1, 3 prove only that the caller is *a* GitHub Actions workflow. An empty `allowed_owners` denies everything, which is the correct reading of "deployed without being told who may use it". ### Pinned keys Set `/jwks-document` to a JWKS and the function verifies against it without any outbound call to the issuer. That is how a GitHub Enterprise Server deployment behind restricted egress works, and how the LocalStack harness has an issuer at all. ## Endpoints ### `GET /healthz` No auth, no storage read. A health check that reads DynamoDB turns a throttled table into an unhealthy service; this endpoint's only job is to say the function is warm and the package imported, which, given a compiled `pydantic-core`, is a genuinely useful thing to know. ```json {"status": "ok", "service": "tremvok", "version": "0.1.0"} ``` ### `POST /v1/deployments` ```json { "delivery_id": "18234:1:production:deploy", "environment": "production", "status": "success", "target": "s3-cloudfront", "mode": "deploy", "version": "1.4.0", "url": "https://magmamoose.com/", "commit": "0123456789abcdef", "run_url": "https://github.com/MagmaMoose/website/actions/runs/18234", "actor": "CalebSargeant", "verified": true, "duration_ms": 41200, "detail": null } ``` `repository` is **not** a field. It comes from the token, which is what makes recording against another repository inexpressible rather than merely rejected. `extra: "forbid"` means sending it anyway is a `422`, not a silent drop. `status` is one of `success`, `failure`, `skipped`, `rolled-back`. `target` is one of `s3-cloudfront`, `lambda-zip`, `terragrunt`, `other`. `url` and `run_url` must be `http(s)`. a notification renders them as links, and a `javascript:` URL in a chat card is a phishing primitive. `detail` is an optional string (max 2000 characters) for a human-readable note about the deployment. Response: ```json {"deployment_id": "9f2c…", "repository": "MagmaMoose/website", "recorded_at": "2026-08-19T07:41:22.104Z", "duplicate": false, "notified": {"slack": true, "teams": false}} ``` A repeat of the same `delivery_id` returns `200` with `duplicate: true` and sends nothing. It is deliberately **not** a `409`: the caller retried a notify step, which is correct behaviour, and a 4xx there would fail a job whose deploy succeeded. `notified` lists every configured sink (`slack`, `teams`) and reports whether the POST succeeded. Unconfigured sinks are absent from the map. A failed notification never fails the request. ### `GET /v1/deployments?environment=&limit=` Query parameters: | Parameter | Type | Default | Constraints | Description | | --- | --- | --- | --- | --- | | `environment` | string | none | max 100 chars | Filter to one environment. Omit to return records across all environments. | | `limit` | integer | `20` | 1-100 | Maximum records to return. | The calling repository's history, newest first. There is no `repository` parameter: you read your own. Cross-repository reads are a dashboard feature and want a different credential than a workflow token. ## Storage One DynamoDB table, one partition per repository: ```text pk = repo#/ sk = dep## the record pk = repo#/ sk = dedup# the idempotency token ``` Both carry `expires_at`, so nothing survives the retention window. Capacity is **provisioned**, not on-demand: on-demand cannot be capped, and a table that can scale itself has no cost ceiling. --- # Architecture Source: docs/architecture.md URL: https://docs.magmamoose.com/tremvok/architecture/ Two surfaces, one repository, no shared imports. ```text GitHub Actions runner ┌──────────────────────────────────────────────────────────────────┐ │ action.yml (composite, glue only) │ │ ├─ validate-inputs.sh inputs ↔ target, or a hard error │ │ ├─ resolve-mode.sh event → deploy | preview │ │ ├─ preflight.sh fork / no credential → skip │ │ ├─ assume-role.sh OIDC → STS → short-lived creds │ │ ├─ pages · s3 · lambda · tg · ansible · cf │ │ ├─ verify-live.sh curl status + header, retried │ │ ├─ collect-outcome.sh one status every sink shares │ │ ├─ notify-{pr,webhook}.sh │ │ └─ record-deployment.sh ──────────────┐ │ └─────────────────────────────────────────┼─────────────────────────┘ │ OIDC-authenticated HTTPS ▼ API Gateway → Lambda (FastAPI + Mangum) ├─► DynamoDB (90-day TTL) └─► Slack / Teams ``` ## One action, ten targets `target` selects the adapter; everything before and after it is shared. The parts that are not target-specific, resolving the mode from the event, the honest skip, verification, the outcome, the three notification sinks, are written once and every target gets them, which is the argument for one action rather than ten. The cost of a target enum is that a caller can pass an input belonging to a different target. Silently ignoring it is what would make the Marketplace listing dishonest, so `validate-inputs.sh` runs first, before the checkout, and refuses the run with every misplaced input named at once. Applicability comes from `scripts/lib/input-targets.json`, generated from the input descriptions in `action.yml`, so the page a caller reads and the check the run performs are built from the same source and cannot disagree. ## Why the action is bash over a thin YAML file `action.yml` maps inputs to environment variables and runs a script. That is all it does. The alternative, conditions and string assembly in YAML expressions, cannot be tested, cannot be run locally, and produces its failures inside a runner. Everything in `scripts/` runs under `bats` with `aws`, `curl`, `terragrunt` and `ansible-playbook` stubbed, so a test can assert the exact command line a deploy would have issued, including the flags that only matter when they are wrong. Python is used for the things that never run on a caller's runner in the deploy path: the two generators, the repo-shape linter, the Lambda packager, and the pytest contract suite. Adding a Python dependency to a target adapter would mean a `setup-python` step on every AWS run, and put that code outside the bash contract the other 300-odd tests enforce. ## The one job the action hands back `actions/deploy-pages` needs `pages: write` and the `github-pages` environment, and a composite action can declare neither. So `target: github-pages` builds and stages the artifact and the caller publishes it. That is the only place an `environment:` is load-bearing: the Terragrunt apply gate is the action's own logic (`approval-gate.sh` reads the pull request's reviews), and needs none. On a push to the default branch there is no pull request in the event, so `resolve-merged-pr.sh` finds the one the commit was merged from first, and on a manual run `terragrunt-pull-request` names it outright. It is also why that target takes no destination input. There is one Pages site and no preview destination for it, so a pull request (`mode: preview`) and a dry run build without staging an artifact, and nothing but the mode decides that. ## The guards, and what each one is for Every one of these is a failure that happened in a hand-rolled `deploy.yml` somewhere in the fleet. | Guard | The failure it prevents | |---|---| | Refuse to sync an empty artifact directory | a build that quietly produced nothing, plus `sync --delete`, empties the live site, and exits `0` | | `set -o pipefail` everywhere; never `cmd \| tee` | `tee`'s exit code masked an auth failure and the run "reported success" | | Verify a **header**, not just a `200` | a deploy that uploads but does not bind: the old version keeps serving and everything looks green | | Immutable artifact keys | overwriting a published key changes the code behind a version somebody already reviewed | | Compare the deployed `CodeSha256` | "the API accepted my request" is not "the function runs my code" | | A preview never moves an alias, and never deploys a Worker version | a pull request proving the artifact publishes must not change what production serves | | `workflow_dispatch` pinned to the default branch | "Run workflow" from a topic branch publishes it to production, and looks like a normal deploy | | An input that belongs to another target is an error | a caller passing `s3-bucket` to `target: ansible` gets a mistake reported, not a run that quietly ignores half its configuration | | Terragrunt applies the **saved** plan | re-planning at apply time means what lands is a plan resembling the reviewed one, not the reviewed one | | Ansible re-runs in check mode | a zero exit proves the playbook ran; only a second run finding nothing left to change proves it converged | | A pinned, checksum-verified tofu/terragrunt, and a pinned Wrangler | the binary that publishes to production is the one input nobody reviews when it floats | | Publish the check run even with **zero** stacks | a required check that never reports blocks the pull request forever | | An unreadable review list is an error, not "nobody approved" | the difference between "wait for approval" and "apply without one" | | "No merged pull request" and "the API could not be read" are different exit codes | an outage on the push path would otherwise read as an unapproved merge, and be reported as one | | Probe the terragrunt endpoints before the first plan | terragrunt buffers plan output to a file, so an unreachable state backend is a silent wait until the timeout, not an error | | The playbook does not inherit the action's Vault token unless asked | a token scoped to three fields becomes one every task, role and collection can use, by accident | | Honest skips for forks and unwired repositories | an expected policy outcome presenting as a broken credential | | Failure-isolated sinks | a chat outage failing a successful deploy, inviting a re-run that deploys again | ## The target adapter boundary `target` selects a script. The resolve → deploy → verify → notify → record skeleton is target-agnostic, so a new target is one script, one gated step, and one bats file. `cloudflare-workers` is that claim being tested: an adapter for a provider the skeleton was not designed around, added without touching the skeleton. It maps the two modes onto two Wrangler commands (`deploy`, and `versions upload --preview-alias` for a version that takes no production traffic) and inherits the resolved mode, the honest skip, verification, the outcome and the three sinks unchanged. Kubernetes deploy *status* and the GitHub Deployments API slot in behind the same interface. ## The API, and why it is not just webhooks v1 of the design had no backend: Slack and Teams are incoming webhooks, and the pull-request comment uses `GITHUB_TOKEN`. That still works, leave `api-url` empty and nothing calls the service. The backend earns its place when you want either of two things: **Notifications without a secret in every repository.** With the API, the Slack and Teams URLs live in one Parameter Store entry that the Lambda reads. A consumer repository holds no credential at all: it authenticates with a GitHub OIDC token minted for that run, expiring in minutes, carrying a `repository` claim it cannot forge. **Deployment history.** "When did production last change, and to what?" is not answerable from workflow logs that expire, and it is the question every incident starts with. The security model is the interesting part, and it is deliberately narrow: the `repository` a record lands under is the token's claim rather than a request field, so recording a deployment against someone else's repository is not *expressible*. And because GitHub issues an OIDC token to every repository on github.com, a valid signature alone proves only that the caller is *a* workflow, `allowed_owners` is what makes it one of ours, and an empty list denies everything. ## Idempotency The action derives a `delivery_id` of `:::`. A retried notify step inside the same attempt is the same delivery; a re-run of the job is a new one. The API takes an idempotency token in DynamoDB with a conditional put **before** writing the record, and deletes the token again if the record write fails, so a failed record is retryable rather than permanently swallowed by its own dedup marker. The property this buys is that **notifications are exactly-once**. Duplicate history rows would be cosmetic; a second Slack ping for the same deploy is the thing humans actually notice. ## Why the OIDC verifier has no dependencies The obvious implementation is PyJWT, which needs `cryptography`: an 8 MB platform-specific wheel that has to be cross-built for the Lambda's architecture and would dominate the package. Verifying an RSA PKCS#1 v1.5 signature is `pow(sig, e, n)` and a constant-time compare against a fixed prefix, thirty lines of integer arithmetic. This is safe to hand-roll in a way that *signing* would not be: verification touches no secret, so there is no timing channel, and the comparison is `hmac.compare_digest` regardless. `tests/test_oidc.py` signs real tokens with `cryptography` (a dev dependency) and checks that `alg: none`, HS256-with-the-public-key, a tampered payload, a wrong audience, a wrong issuer and an expired token are all rejected. --- # Azure: a Function or API Management? Source: docs/azure-functions-or-api-management.md URL: https://docs.magmamoose.com/tremvok/azure-functions-or-api-management/ Both Azure targets give a repository an HTTP endpoint it deploys into: [`azure-functions-zip`](setup.md#azure-functions-zip) publishes code to a Function App, [`azure-apim-policy`](setup.md#azure-apim-policy) publishes policies to an API Management API. They suit different jobs, and the job decides. ## API Management, when the endpoint is glue The endpoint receives a request, checks it, reshapes it and hands it on: to a Storage queue, a Service Bus topic, another API. A webhook receiver that verifies a signature and queues a pointer is the typical case. - **There is no code to host.** The logic is a policy: XML with C# expressions, compiled by the gateway. No runtime version to pin, no package to build, no worker to start, and nothing to migrate when a hosting plan is retired. - **Azure services by managed identity, in one element.** `authentication-managed-identity` inside `send-request` calls Storage, Service Bus or Event Hubs with the instance's own identity. For a Storage queue it is the Put Message call the SDK makes, with the same message time-to-live (`messagettl`) and the same role, `Storage Queue Data Message Sender`, scoped to the one queue. Answer the caller only after the queue has returned `201`, and a failed enqueue is still a failed delivery the sender can see. Wrap the call in `retry` if you want the SDK's retries. - **Cheap at low volume.** The Consumption tier includes a million calls a month. - **Checked on publish.** API Management refuses a policy whose XML or expressions do not compile, and `azure-apim-policy` puts the previous set back when it does. ## A Function, when the endpoint is a program - It needs a library, an SDK or more logic than reads comfortably as policy expressions. A few dozen lines of C# in attributes is the practical ceiling. - It needs unit tests. A policy expression can only be exercised against a live gateway. - It consumes rather than answers: queue, timer, blob or Event Grid triggers. API Management only answers requests; it cannot drain a queue or run on a schedule. - It works for longer than a caller should wait, or keeps state between calls. Linux Consumption retires on 30 September 2028. Create a new Function App on Flex Consumption. ## What they share - **The same sign-in.** `azure-client-id`, `azure-tenant-id` and `azure-subscription-id`, and one federated credential per repository. - **Cold starts** on their consumption tiers. A caller with a hard deadline (a chat platform's outgoing webhook may allow five seconds, a git host ten) should get its answer from a short path, with the slow work after a queue. - **No preview destination** on the consumption tiers. A pull request publishes nothing unless the Function App has a slot. ## In one line each | The endpoint | Target | |---|---| | verifies, reshapes, and queues or forwards | `azure-apim-policy` | | needs a package, a library or tests | `azure-functions-zip` | | is triggered by a queue, a timer or a blob | `azure-functions-zip` | | must answer within seconds but do slow work | `azure-apim-policy` in front, a queue, a worker behind it | ## Who owns the policy If the team that runs the infrastructure owns the policy, and it changes with the infrastructure, keep it in the infrastructure code (Terraform's `xml_content`, a Bicep `policies` resource) and this target is not needed. Use `azure-apim-policy` when an application repository owns the endpoint's behaviour and ships it on its own cadence, the way function code is shipped. Give each policy one owner: two writers overwrite each other on every run. --- # Configuration reference Source: docs/configuration.md URL: https://docs.magmamoose.com/tremvok/configuration/ The action's inputs live in the [action reference](action-reference.md). This page covers the other two configuration surfaces: the API's environment variables and the Terraform module's input variables. You only need this page if you deploy the optional deployment-record API. The action itself needs none of it. ## API environment variables Terraform sets all of these on the Lambda function. Set a wrong value and it shows up in a plan diff, which is the reason they're environment variables rather than parameters. | Variable | Type | Default | Required | What it does | | --- | --- | --- | --- | --- | | `TREMVOK_TABLE` | string | `""` | yes | DynamoDB table holding deployment records. An empty value makes every write fail. | | `TREMVOK_ALLOWED_OWNERS` | comma-separated list | `""` | yes | GitHub owners whose tokens may write. Lower-cased on read. **Empty denies everyone**, which is deliberate: `authorize()` is deny-by-default, so a misconfigured deploy records nothing rather than accepting anyone's token. | | `TREMVOK_PARAMETER_PREFIX` | string | `""` | no | SSM path prefix the notification webhooks are read from. A trailing `/` is stripped. Empty means no sink is configured, which is the normal case, not an error. | | `TREMVOK_OIDC_AUDIENCE` | string | `tremvok` | no | Audience claim the token must carry. Must match the action's `api-audience` input. | | `TREMVOK_OIDC_ISSUERS` | comma-separated list | `https://token.actions.githubusercontent.com` | no | Accepted `iss` claims. Add your GitHub Enterprise Server issuer here; setting it replaces the default rather than adding to it. | | `TREMVOK_RETENTION_DAYS` | integer | `90` | no | How long a record lives. Written as a DynamoDB TTL on `expires_at`, so expiry costs nothing and needs no sweeper. | | `AWS_ENDPOINT_URL` | string | unset | no | Points boto3 at LocalStack. Set by the local harness, never in production. | Read once per execution environment and cached, so changing one needs a new deployment, not a new request. ### Secrets are not here Slack and Teams webhook URLs are SSM Parameter Store `SecureString` values under `TREMVOK_PARAMETER_PREFIX`, never environment variables. An environment variable is plaintext to anyone holding `lambda:GetFunctionConfiguration`, which is a much wider blast radius than it looks. Parameter Store gives you KMS at rest and an IAM-scoped read for nothing. | SSM key (relative to `TREMVOK_PARAMETER_PREFIX`) | What it holds | | --- | --- | | `slack-webhook` | Slack incoming webhook URL | | `teams-webhook` | Microsoft Teams incoming webhook URL | | `jwks-document` | Pinned JWKS for air-gapped or GitHub Enterprise Server deployments; see [API reference](api.md#pinned-keys) | All three are optional. A missing key means that sink is not configured. !!! warning "Storing a webhook URL with the AWS CLI" `aws ssm put-parameter --value https://hooks.slack.example/...` downloads the URL and stores its contents. The CLI expands any argument starting with `http://` or `https://` into the body of that URL, and the error blames the wrong thing. Use `--cli-input-json`, which isn't subject to the expansion on any CLI version. `terraform/localstack/seed.sh` does it that way. ## Terraform module variables `terraform/modules/tremvok-api` is the whole stack. Defaults are read from `variables.tf` in this run. | Variable | Type | Default | What it does | | --- | --- | --- | --- | | `name` | string | `tremvok-api` | Name prefix for every resource the module creates. | | `environment` | string | none | Environment label, required. | | `region` | string | none | AWS region, required. | | `artifact_bucket` | string | none | Bucket holding the built Lambda package. | | `artifact_version` | string | none | Key of the package to deploy. | | `architecture` | string | `arm64` | Lambda architecture. Must match what `build_api_zip.py --arch` produced. | | `allowed_owners` | list(string) | `[]` | Sets `TREMVOK_ALLOWED_OWNERS`. Empty denies everyone. | | `oidc_audience` | string | `tremvok` | Sets `TREMVOK_OIDC_AUDIENCE`. | | `retention_days` | number | `90` | Sets `TREMVOK_RETENTION_DAYS`. | | `log_retention_days` | number | `14` | CloudWatch log group retention. | | `throttle_rate_limit` | number | `2` | API Gateway steady-state requests per second. | | `throttle_burst_limit` | number | `10` | API Gateway burst capacity. | | `reserved_concurrency` | number | `5` | Lambda reserved concurrency. | | `memory_size` | number | `512` | Lambda memory in MB. | | `timeout` | number | `20` | Lambda timeout in seconds. | | `parameter_prefix` | string | none | Sets `TREMVOK_PARAMETER_PREFIX`. | | `alarm_actions` | list(string) | `[]` | SNS topics the CloudWatch alarms notify. Empty means the alarms exist but tell nobody. | | `localstack` | bool | `false` | Swaps API Gateway for a Lambda Function URL and skips the alarms. Never set this in a real account. | | `tags` | map(string) | `{}` | Tags applied to every resource. | !!! warning "The architecture has to match the package" `pydantic-core` is a compiled wheel. An arm64 package on an x86_64 function applies cleanly, plans green, and then fails on the first request with `No module named 'pydantic_core._pydantic_core'`. `build_api_zip.py --arch` and `architecture` must agree. The Makefile derives both from `uname -m`. ## The cost ceiling AWS has no spend cap, and Budgets only report after the fact. Three independent caps hold the bill down, and any one of them alone would leave a hole: | Cap | Variable | Default | What it stops | | --- | --- | --- | --- | | API Gateway throttle | `throttle_rate_limit`, `throttle_burst_limit` | 2/sec, burst 10 | Request volume, before it reaches Lambda | | Lambda reserved concurrency | `reserved_concurrency` | 5 | Parallel executions, so a slow dependency can't fan out | | Provisioned DynamoDB | not configurable | provisioned, not on-demand | On-demand billing turning a free table into a bill. A throttled write is a retry, not an outage. | Record expiry is a DynamoDB TTL on `expires_at`, so old records cost nothing to remove. `history_scan_limit` is `200` and isn't configurable. It bounds how many items a history query reads, because DynamoDB applies a `FilterExpression` *after* `Limit`: asking for 20 production deployments could otherwise scan the whole partition. --- # Tremvok Source: docs/index.md URL: https://docs.magmamoose.com/tremvok/ One GitHub Action for the whole deploy side. It's the counterpart to [Diatreme](https://github.com/MagmaMoose/diatreme). Diatreme answers *"what version, and is it released?"*. Tremvok answers *"get that live, prove it, and tell everyone."* ```mermaid flowchart LR A[push / merge] --> B[release.yml → Diatreme] B -->|version · tag · release · promoted image| C[deploy.yml → Tremvok] C -->|target| D[github-pages · s3-cloudfront · lambda-zip · terragrunt · ansible · cloudflare-workers · gitops-pr] D -->|curl 200 + header · a second check-mode run| E[verify it actually went live] D -->|PR comment · Slack · Teams · history| F[humans] ``` Pick a target, pass that target's inputs. An input belonging to a different target is a hard error naming both, raised before the checkout. That's what keeps one listing able to describe ten jobs honestly. ## Start here - **[Setup](setup.md)**: the workflow for each target, the IAM role, and the secrets. Start here to add a `deploy.yml` to a repository. - **[Action reference](action-reference.md)**: every input and output, which target each one applies to, and the permissions each target needs. Generated from `action.yml`. - **[Migrating to v2](migration.md)**: if you are on `@v1` or on the `deploy/` entry point. - **[Architecture](architecture.md)**: how the pieces fit, and the specific production failure each guard exists to prevent. - **[API reference](api.md)**: the deployment-record service: endpoints, the OIDC model, the storage schema. - **[Infrastructure](https://github.com/MagmaMoose/tremvok/blob/main/terraform/README.md)**: the free-tier accounting, the cost ceiling, and what a LocalStack run does not prove. ## What Tremvok is not **It does not build your app.** The build is legitimately per-product. One repository stages a static site with a Python script, another bakes an API base URL into a Vite bundle, a third vendors a core package. The [standard](https://github.com/MagmaMoose/standard) repository already draws that line. Tremvok picks up *after* `npm run build` and owns everything from there. **It does not cut versions or releases.** That is Diatreme. **It does not reconcile GitOps.** Where a service is deployed by a cluster-side reconciler, Tremvok's job is to propose the change to Git (`target: gitops-pr`), report and verify, not to apply. --- # Migrating to v2 Source: docs/migration.md URL: https://docs.magmamoose.com/tremvok/migration/ v1 is the docs-only action. v2 is one action covering multiple deployment targets, so the input surface had to grow a selector and the docs inputs had to move out of the way of it. **`@v1` is frozen at v1.0.18 and keeps working.** It is not deprecated by this. Migrate when you want another target, or when you want the input validation. That sentence used to read "`@v1` keeps working exactly as it does today", and for a day it was false. The release job moves the floating major tag onto every stable release, and GitVersion cut both breaking changes as patches, so `v1` was force-moved onto v1.0.19 and then v1.0.23: every consumer pinned to `@v1` received the v2 contract without asking for it, and nine repositories went red on `unknown target 'none'`. `v1` now points at v1.0.18, the last release that actually speaks the v1 contract, and `GitVersion.yml` makes a breaking change bump the major so the tag can never wander again. ## What changed, and why `target` at v1 meant *where the built site goes*. At v2 it means *what to deploy*, which is the collision that forced a major: ```yaml # v1 - uses: MagmaMoose/tremvok@v1 with: target: github-pages toolchain: uv strict: true # v2 - uses: MagmaMoose/tremvok@v2 with: target: github-pages pages-toolchain: uv pages-strict: true ``` The docs target is now named for the one place it publishes, so `target` says both things at once and there is no second destination input under it. Every other docs input gained a `pages-` prefix: with multiple targets in one action, a bare `toolchain` or `strict` cannot say whose it is. The prefix is also what the validator keys on, so a misplaced input is caught rather than ignored. ## Renames | v1 | v2 | | --- | --- | | `target: github-pages` | `target: github-pages`, and it now selects the deploy target itself | | `toolchain` | `pages-toolchain` | | `docs-group` | `pages-dependency-group` | | `requirements` | `pages-requirements` | | `python-version` | `pages-python-version` | | `strict` | `pages-strict` | | `site-dir` | `pages-site-dir` | | `lint` | `pages-lint` | | `profile` | `pages-profile` | | `readme-budget` | `pages-readme-budget` | | `markdownlint` | `pages-markdownlint` | | `target: cloudflare-pages` | **removed**: publish a built site with `target: cloudflare-workers` | | `cloudflare-project`, `cloudflare-account-id`, `cloudflare-api-token`, `cloudflare-branch` | **removed** with it. The Workers target takes `cloudflare-api-token` and `cloudflare-account-id` of its own, and reads the rest from your Wrangler config | | `require-access` | **removed** with it | | `stage-pages` | **removed**: it was already a deprecated alias, and staging is no longer a choice | There is no `docs-target` at v2, and nothing replaces it. GitHub Pages is one site with no preview destination, so a pull request (`mode: preview`) and a dry run build without staging an artifact, and a push to the default branch stages one. The mode decides, which is what the mode means for every other target too. If you tracked a `docs-*` prefixed pre-release of v2 rather than `@v1`, the rename is mechanical: `docs-` becomes `pages-`, `target: docs` becomes `target: github-pages`, and `docs-target` comes out. An input that no longer exists is a hard error naming the target, so a missed one fails the run before the checkout rather than being ignored. `working-directory` and `checkout` are unchanged: they genuinely apply to every target. ## Outputs | v1 | v2 | | --- | --- | | `toolchain` | `pages-toolchain` | | `target` | `target`, now the selector you passed in, not the docs destination | | `site-dir` | unchanged | | `page-url`, `deployment-url` | **removed**: the Pages URL comes from your own `deploy-pages` step, and any other target's published URL is `url` | ## The reusable workflows are gone `.github/workflows/docs.yml` and `docs-github-pages.yml` were the v1 quickstart. They are removed at v2: one action is the whole product, and a second callable surface for one target only was a place for the two to disagree. The half they carried that the action cannot is the Pages deploy: `actions/deploy-pages` needs `pages: write` and the `github-pages` environment, and a composite action can declare neither. That becomes a job in your own workflow, the shape is in [Setup](setup.md), and it is about ten lines. It is the only place in the action where an `environment:` is load-bearing; the Terragrunt apply gate is the action's own logic and needs none. Callers who used `docs.yml` for Cloudflare Pages need a different target: `cloudflare-workers` publishes a built directory with Wrangler, needs no GitHub permission, and completes inside the action. [Setup](setup.md#cloudflare-workers) has the job. ## The subdirectory entrypoint is gone `MagmaMoose/tremvok/deploy@v1` no longer exists. Its three targets are `target: s3-cloudfront`, `target: lambda-zip` and `target: terragrunt` on the root action, with these renames: | `deploy/` | v2 | | --- | --- | | `role-to-assume` | `aws-role-to-assume` | | `role-duration-seconds` | `aws-role-duration-seconds` | | `bucket` | `s3-bucket` | | `key-prefix` | `s3-key-prefix` | | `delete-orphans` | `s3-delete-orphans` | | `distribution-id` | `cloudfront-distribution-id` | | `site-url` | `cloudfront-site-url` | | `function-name` | `lambda-function-name` | | `function-alias` | `lambda-function-alias` | | `version-label` | `lambda-version-label` | | `terraform-root` | `terragrunt-root` | | `check-name` | `terragrunt-check-name` | It never appeared in a release note, and the three files in `examples/` that pointed at it were pointing at the root action anyway, which is a large part of why the surfaces merged. ## Behaviour changes worth knowing - **A wrong input now fails the run.** At v1 an input the action did not declare produced a warning and was ignored. At v2 an input belonging to another target is an error naming both, raised before the checkout. - **The Terragrunt apply uses the saved plan.** Plan writes `-out`, apply applies that file. When the saved plan has gone stale the run says so in the log and re-plans rather than refusing, `PLAN SOURCE:` in the log names which one ran. - **A plan-only Terragrunt run reports success, not failure.** It deployed nothing on purpose. At v1 the notification called that a failed deploy. - **`schedule` and `pull_request_review` resolve.** `mode: auto` used to fail on both, which broke the Terragrunt drift run on its own cron. --- # Roadmap Source: docs/roadmap.md URL: https://docs.magmamoose.com/tremvok/roadmap/ Tremvok's scope is **deployment orchestration and notification**: the deploy-side counterpart to [Diatreme](https://github.com/MagmaMoose/diatreme). One action covering several deployment targets, not a family of narrow ones. Status here is the single source; if a claim about maturity appears anywhere else in this repo, it is wrong. ## Shipped - **`target: github-pages`**: detect the toolchain, build the MkDocs site strictly, stage the Pages artifact for your deploy job, and verify the published URL answers. A pull request builds without staging, because one site with no preview destination is what `mode: preview` already means here. - **`target: cloudflare-docs`**: the same strict MkDocs build as `github-pages`, published to Cloudflare Workers Static Assets instead. The site Worker has no route and no workers.dev URL; a router Worker on `docs.magmamoose.com` reaches it over a service binding, so one hostname serves every repository by path and Cloudflare Access gates the person visiting rather than the router. `cloudflare-docs-require-access` refuses to publish a private site that no Access application covers, and treats "could not tell" as a refusal. The same build emits the **docs corpus** (`llms.txt`, `llms-full.txt` and a search index) and, with a bucket named, publishes the index to R2 as `index/.json` after the site deploys, so a fleet of docs sites is one corpus written at build time rather than crawled afterwards. A repository that is a house tool ships a `capability.json` to `capability/.json` in the same bucket, validated against the MCP's schema on every run: that is what lets an agent be told "no house tool does this" rather than "nothing was found". - **`target: s3-cloudfront`**: sync a built static site with per-class cache headers, invalidate CloudFront, previews under their own key prefix. Refuses to sync an empty artifact directory. - **`target: lambda-zip`**: immutable S3 keys, published versions, the alias moved only on a deploy, and the deployed `CodeSha256` verified against the local artifact. - **`target: terragrunt`**: discover, plan, gate on an independent approval, apply; a rolling pull-request comment with redacted plan excerpts, and a check run that makes apply-before-merge enforceable. Replaces Atlantis and its stored IAM credential. - **`target: ansible`**: pinned Ansible, galaxy requirements, a playbook run over SSH with keys that cannot reach a log, check mode by default on a pull request, and a second check-mode run that proves the playbook converged. - **`target: cloudflare-workers`**: a Worker and its static assets published with a pinned Wrangler. A push deploys; a pull request runs `versions upload --preview-alias pr-`, so the preview has its own URL and takes no production traffic. The Wrangler config keeps owning the asset directory, the routes and 404 handling. Refuses to publish an empty asset directory. - **`target: azure-functions-zip`**: publish a zip to an Azure Function App over OIDC, then poll until it answers. Corroborates the exit code against `WEBSITE_RUN_FROM_PACKAGE` (the CLI has been observed lying), refuses a package whose `functions.metadata` is not at the root, and previews to a slot when one is configured. - **`target: azure-apim-policy`**: publish policy documents to an existing API Management API over OIDC — `api.xml` to the API scope, one file per operation. Reads the current set first, and if any document is refused by the gateway it puts every replaced scope back and names the cause. Refuses a document named after an operation the API does not have. - **`target: gitops-pr`**: deploy a released image through the kustomize overlays a GitOps controller applies, by pull request. A published release opens the deploy PR for the first overlay; merging it opens exactly what it changed for the next, so a later environment only gets a build the one before it ran. Only the `newTag` line changes, one open deploy PR per overlay, and an overlay is never moved backwards. - **Preview claims for label-driven preview controllers** (`gitops-pr`, `gitops-preview-labels`): one open pull request per preview label. The first pull request to take a label holds it; one that takes it later loses the label again and is told which pull request holds it, so a controller with `filter.limit: 1` never switches environments silently. Deploys nothing itself. - **Post-deploy verification**, **notifications** (sticky pull-request comment, Slack, Teams), and the **deployment-record API**. ## The entry-point rule, reversed This page used to say that additional targets would get their own entry point rather than a mode flag, because "a `job:` enum where most values error is a listing that cannot say what it does". **That position is reversed**, and one action now carries every target. The objection was right about the failure mode and wrong about the cause. A target enum becomes a listing that cannot describe itself when the inputs that do not apply to the selected target are *silently ignored*. The listing then documents an input surface that does nothing for most callers. So the build removes the silence: - **Every input is validated against the selected target.** An input that does not apply is a hard error naming the target, raised before the checkout. `target: ansible` with `s3-bucket` set is a mistake, and it is reported as one, with every other mistake in the same run. - **Applicability is derived, not maintained.** `scripts/gen_input_targets.py` reads it out of the input descriptions in `action.yml` into the map the runtime validator uses, so the documentation and the check cannot disagree. - **Input names carry their target**: `pages-`, `s3-`, `cloudfront-`, `lambda-`, `terragrunt-`, `ansible-`, `cloudflare-`, with `aws-` for what the AWS targets share and no prefix for what everything shares. What the split cost was worse than what it bought: three entry points meant three Marketplace-facing surfaces, an `examples/` directory pointing at the wrong one, and a README, a roadmap and a repository description that each described a different product. ## Next - **Rollback as a first-class mode.** `mode: rollback` resolves today but no target implements re-publishing a previous version. Deployment history exists to make it possible; wiring it is the remaining work. - **Verifying a preview without pasting its URL in.** `verify-url` is a fixed input, so the per-run URL a Workers preview produces (the `url` output) reaches the comment, the webhooks and the deployment record, but nothing curls it. Feeding that output into the verify step is what's missing. ## Not planned - **Building your app.** The build is legitimately per-product. Tremvok picks up at "the artifact exists". - **Reconciling GitOps.** Where a service is deployed by a cluster-side reconciler, Tremvok's job is to propose the change (`gitops-pr`), report and verify, not to apply. --- # Setting Tremvok up Source: docs/setup.md URL: https://docs.magmamoose.com/tremvok/setup/ Pick a target, add the job, grant the permissions that target needs. The [action reference](action-reference.md) has every input and the exact permission block per target; this page is the task-shaped version. ## The workflow, per target ### `github-pages` `actions/deploy-pages` requires `pages: write` and the `github-pages` environment, and a composite action can declare neither. So the action builds and stages the artifact, and a job of yours publishes it. The environment name is fixed. GitHub creates `github-pages` when you set the Pages source to "GitHub Actions", and `deploy-pages` expects that name, so this job is boilerplate, not a decision: ```yaml permissions: { contents: read } jobs: build: runs-on: ubuntu-latest steps: - uses: MagmaMoose/tremvok@v2 with: target: github-pages pages-strict: true deploy: needs: build if: github.event_name != 'pull_request' runs-on: ubuntu-latest permissions: { pages: write, id-token: write } environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - id: deployment uses: actions/deploy-pages@v5 ``` There's nothing to set for a pull request. GitHub Pages has one site and no preview destination, so publishing to it is publishing, and a pull request (which resolves to `mode: preview`) builds and checks without staging an artifact. A dry run does the same. The build is the check, and it can't publish by accident. Set **Settings → Pages → Source = "GitHub Actions"** once per repository. #### Search, social and agent metadata Both docs targets finish the build by giving every page the metadata MkDocs Material leaves out. The step edits the built HTML, is on by default (`pages-seo`), and needs no credentials and no network: - **Its own meta description.** Material prints `site_description` on every page without a `description:` in its front matter, so a search engine sees one sentence repeated across the site. Each of those pages gets its first paragraph of prose instead, at most 155 characters and unique across the site. Warnings, tables, code, lists and lines that are only links are skipped. The home page keeps `site_description`, and when its title is the bare site name, the lead clause of `site_description` joins it (`Tremvok - One GitHub Action for the whole deploy side`). - **Open Graph and Twitter tags**, so a link pasted into Slack or LinkedIn unfurls as a card. - **A JSON-LD graph**: the `WebSite` and its publisher on every page, and a `TechArticle` and a `BreadcrumbList` built from the nav on every page but the home page. - **A markdown twin**: the page's source at `/index.md` (the llmstxt.org convention), announced with ``, its relative links resolved the way MkDocs resolves them for the HTML so they still work from where the twin lives. On `cloudflare-docs`, `llms.txt` links the twins. Configure it under `extra.seo` in `mkdocs.yml`. `extra` is a dict, so it merges through `INHERIT` and a shared base can set it once for every site. Every key is optional: ```yaml extra: seo: locale: en_GB # og:locale, and inLanguage (en-GB) in the JSON-LD image: # the link-preview card url: https://www.example.com/og/card.png width: 1200 height: 630 alt: Example docs # defaults to site_name publisher: # use the @id your own site's JSON-LD already has type: Organization id: https://www.example.com/#organization name: Example url: https://www.example.com/ logo: https://www.example.com/logo.png same_as: [https://github.com/example] # author: the same shape; defaults to the publisher, then to site_author # twitter: "@handle" ``` A page keeps whatever it already has: a description that is not `site_description` (from front matter or a hook of your own), Open Graph tags once `og:title` is present, Twitter tags once `twitter:card` is, JSON-LD once any `application/ld+json` block is, and a twin or twin link that exists already. The same rules make a second run change nothing. Canonical links, `og:url` and the JSON-LD need an absolute address, which is `site_url`. On `cloudflare-docs` the router address stands in when `site_url` is unset, and the step warns, because MkDocs has then written no canonical links and an empty `sitemap.xml`. #### Agent readiness A step after the metadata makes the site usable by AI agents, on by default (`pages-agent-ready`) and configured under `extra.agents`: an Agent Skills index at `/.well-known/agent-skills/index.json` with a skill that says what the site covers and how to read and cite it, WebMCP tools on every page (search, read a page as markdown, list and open pages), and an `/auth.md` for a site served at the root of its host. [Agent readiness](agent-readiness.md) has the details, and the steps a build cannot take for you: DNS records, markdown negotiation on a host of your own, and OAuth for an MCP server. #### Installing a dependency from a private git repository A docs build often pins its theme straight to a private repository: ```text mkdocs-yourtheme @ git+https://git.example.invalid/your-org/theme.git@v1.1.2#subdirectory=theme ``` That clone is git's own, several processes below the action, so there is no flag to pass a token on. `build-git-credentials` leaves one where git will find it, one ` :` per line: ```yaml - uses: MagmaMoose/tremvok@v2 with: target: github-pages build-git-credentials: | git.example.invalid x-access-token:${{ steps.app-token.outputs.token }} ``` Each line becomes a `url..insteadOf` rewrite carried in `GIT_CONFIG_COUNT` / `GIT_CONFIG_KEY_n` / `GIT_CONFIG_VALUE_n`, which live in the job's environment and end with the job. Requirements files keep pinning the plain URL, so they stay reviewable. Don't reach for `git config --global` in a step of your own instead: a self-hosted runner is a shared, long-lived machine, and a global rewrite leaves the token in `~/.gitconfig` for whatever runs there next. Write the username out, because the forges disagree about it: `x-access-token` goes with a GitHub App installation token, `oauth2` with a GitLab one. Prefer a short-lived App token (`actions/create-github-app-token`) over a personal access token — it expires within the hour and it only reaches the repositories the installation was given. `cloudflare-workers` takes the same input for the same reason: its build runs on the runner too. Every token is masked the moment it is read, and none is ever echoed. A line the action refuses is named by its index and its host, and the host is only quoted when it looks like one, because a bare token pasted onto a line would otherwise be printed into an annotation as public as the repository. ### `cloudflare-docs` The same strict MkDocs build as `github-pages`, published to Cloudflare Workers Static Assets instead of GitHub Pages. The canonical address is `https:////`, and one hostname serves every repository by path: ```yaml permissions: { contents: read, pull-requests: write } jobs: docs: runs-on: ubuntu-latest steps: - uses: MagmaMoose/tremvok@v2 with: target: cloudflare-docs cloudflare-docs-host: docs.magmamoose.com cloudflare-api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }} cloudflare-account-id: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} ``` One job, where `github-pages` needs two. That second job exists only because `actions/deploy-pages` requires `pages: write` and the `github-pages` environment, which a composite action cannot declare. Wrangler requires neither. Three things have to exist before the first run: 1. **`site_url` is the canonical address.** Set it to `https:////`. MkDocs emits `` and its sitemap from it, so leaving it pointed at the old host publishes absolute links to somewhere that is no longer the address. 2. **A `wrangler.toml` at your repository root.** Copy `workers/docs-site/wrangler.toml` and set `name` to `docs-`. It declares `[assets]` and, deliberately, no route and no `workers_dev` URL. 3. **A `[[services]]` block in the router's config**, binding `` to `docs-`. Without it the router 404s your path — a quiet omission, since your own build stays green. A pull request publishes nothing. These Workers carry no route and `workers_dev = false`, so there is no disposable address a preview could be served from; the strict build is the check. That is the same position `github-pages` is in, arrived at differently. #### Why the router uses a service binding The site Workers are unreachable over HTTP. The router on `` calls them through a **service binding**, which is an in-process dispatch on Cloudflare's network rather than a request on the wire. An HTTP proxy would need a public origin hostname for each site — exactly what `workers_dev = false` exists to prevent — and proxying an Access-gated origin would need the router to hold a service token, at which point Access is gating the router rather than the person visiting. #### What the router serves itself The host root is the router's own, so the fleet has one front door for people, crawlers and agents: | Path | What it is | |---|---| | `/` | A landing page listing every site, with its title and summary, or a `302` to your own documentation hub (below) | | `/llms.txt` | An [llms.txt](https://llmstxt.org/) index linking each site's `llms.txt` and `llms-full.txt` | | `/sitemap.xml` | A sitemap index of every site's `sitemap.xml` | | `/robots.txt` | Allows everything, declares content signals, names the sitemap index | | `/.well-known/security.txt` | The RFC 9116 security contact | | `/.well-known/ai-catalog.json`, `/.well-known/api-catalog` | Pointers to the docs MCP server's card, for agent registries | | `/.well-known/agent-skills/index.json` | A skill for the host and every public site's own, re-addressed from the root | | `/webmcp.js` | The landing page's WebMCP tools: list the sites, search them, read a page, open a site | A site's title and summary there are read from its own `llms.txt`, which the build writes from `site_name` and `site_description`. Those two keys in your `mkdocs.yml` are what the root says about your site, and the `[[services]]` block is the only thing to register. The router also sets the security headers every response on the host carries, serves `.txt` and `.md` as UTF-8, and answers `Accept: text/markdown` on a page with that page's `index.md`, so a site Worker needs none of it. If you keep a documentation hub elsewhere, such as a Docs page on your main site, set `LANDING_REDIRECT` under `[vars]` in the router's `wrangler.toml` to its `https` URL. `/` then answers a `302` there instead of serving the landing page, keeping the discovery `Link` header. A client whose first media range is `text/markdown` still gets the index, and every other path above is unchanged. Blank, or anything but an `https` URL, and `/` serves the landing page. Set it only once that page is live: the redirect does not check. The landing page's WebMCP tools go with it: a browser, a scanner's included, then reads the tools of the page it was sent to, so that page needs its own for the host to pass `webMcp`. #### Keeping a private site private `cloudflare-docs-require-access: true` makes the deploy ask Cloudflare which Access applications exist and refuse to publish unless one actually covers `/`: ```yaml cloudflare-docs-require-access: 'true' ``` "The site is behind Access" is otherwise a belief that nothing checks, falsified silently the day an application is renamed or its domain edited. This is the one moment something can ask. The API token needs the **`Access: Apps` read** permission for this. Cloudflare's "Edit Cloudflare Workers" template does not include it, and a `403` is reported as *could not tell* rather than as "nothing covers it" — the two look alike in the response and collapsing them would publish a private site while reporting that it checked. The repository's name also belongs in `PRIVATE_SITES` in the router's `wrangler.toml` before its `[[services]]` block lands. Access gates people, not the router's own reads over the binding, so without it the public landing page, `/llms.txt` and the sitemap index would list the site with the title and summary from its `llms.txt`. #### The docs corpus The build already holds every page it just rendered, so it emits a machine-readable copy of the site at no extra cost: `llms.txt` (a link index) and `llms-full.txt` (every page's text) are written into the site before it is published, and a search index of every page is generated beside it. On by default (`cloudflare-docs-index`), with no credentials and no network. The corpus is what the build rendered, not everything under `docs/`. A file the build left out (`exclude_docs`, `draft_docs`) is not indexed, because its URL would 404; the step's log names each one. `llms.txt` links each page's markdown twin when the metadata step above wrote one, as llmstxt.org asks, and the page itself otherwise. The search index always cites the page. Name a bucket and a deploy also publishes that index to R2 as `index/.json`, which is the corpus the documentation MCP servers read: ```yaml cloudflare-docs-index-bucket: magmamoose-docs-index ``` Only a deploy writes it, and only after the site itself deployed: there is one key per repository, so a pull request would otherwise overwrite the shared corpus with an unmerged branch, and an index published ahead of a failed deploy would cite pages nobody serves. The token needs **R2 object write** on top of the Workers permissions. The upload is not failure-isolated: a run that deployed the site and quietly failed to publish the index would be green while every agent read the previous commit's documentation. #### The capability registry The corpus answers questions about documentation. It cannot answer the one an agent asks *before* it writes a workflow — which house tool already does this, how do I consume it, and if none does, where do I file? Prose has to be interpreted, it does not carry the `uses:` ref, and it cannot say **no**: four pages read and nothing found is indistinguishable from a tool that has not published, and those two lead to opposite actions. So a tool declares what it does, in a file at its own root, and this deploy ships it to `capability/.json` beside the index: ```json { "schema": 1, "repo": "tremvok", "private": false, "file_issues_at": "MagmaMoose/tremvok", "action": { "uses": "MagmaMoose/tremvok@v2", "kind": "composite-action" }, "capabilities": [ { "id": "cloudflare-docs", "summary": "Build an MkDocs site strictly and publish it to Cloudflare Workers.", "ecosystems": ["python", "mkdocs"], "inputs": ["cloudflare-docs-host", "cloudflare-docs-index-bucket"], "excludes": ["a docs site that is not MkDocs", "publishing to GitHub Pages"], "doc": "docs/setup.md" } ] } ``` `cloudflare-docs-capability-file` names it, defaulting to `capability.json`; empty turns it off. **Absent is the normal case** — most repositories are not house tools — and a run that finds no file uploads nothing and says so in its summary. `excludes` is the field that earns its keep, and the one worth writing first. A capability that only says what it covers gets returned for cases it cannot serve, and the symptom is a check that passes having measured nothing. A capability that declares none is warned about. **A declaration that does not validate fails the run**, on a pull request as much as on a deploy. The schema is [`capability.schema.json`](https://mcp.magmamoose.com/schema/capability.schema.json), and the reason for refusing rather than uploading is what the MCP does with a broken document: it reads it as private and reports it as unreadable, counted and never named. A tool that vanished because its JSON broke looks exactly like a tool that declared nothing, from the only side that could notice. Every problem is reported in one run, not one per attempt. Validation runs on a pull request; the upload does not. There is one key per repository, so a preview that wrote would overwrite the shared registry with an unmerged branch — but a declaration only checked on `main` is checked after the merge that broke it. Two fields are the publisher's rather than the file's. `commit` and `generated` are stamped from the run, because a file in a repository cannot know which commit it shipped from. And `private` is republished from the repository's own visibility on the same fail-closed rule as the index: a declaration is public only when it asks to be **and** GitHub says the repository is public. Two visibility rules over one bucket is one rule that eventually disagrees with the other, and the direction it disagrees in is a leak. ### `cloudflare-workers` ```yaml permissions: { contents: read, pull-requests: write } jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7.0.1 - run: npm run build # your build, not Tremvok's - uses: MagmaMoose/tremvok@v2 with: target: cloudflare-workers artifact-path: dist # the Worker's asset directory cloudflare-api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }} cloudflare-account-id: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} ``` Two secrets, and no GitHub permission for the deploy itself: Cloudflare doesn't need one, so `pull-requests: write` is there only for the sticky preview comment. Mint the API token from Cloudflare's **"Edit Cloudflare Workers"** template rather than a hand-picked permission list, or the first deploy of a custom domain fails on a permission nobody thought to grant. Pass the account id as a secret too. **Your `wrangler.toml` (or `wrangler.jsonc`) stays authoritative.** It owns the asset directory, the routes, custom domains and 404 handling, so what ships matches what's reviewed in the repository. The inputs are overrides for the few things a workflow legitimately varies between runs: `artifact-path` is passed as `--assets`, `cloudflare-worker-name` as `--name`, `cloudflare-env` as `--env`, and `cloudflare-config` points at the file when it isn't where Wrangler would look. The mode decides which Wrangler command runs: | Event | Mode | Wrangler | |---|---|---| | push to the default branch, or `workflow_dispatch` | `deploy` | `wrangler deploy`, live on the routes in your config | | pull request | `preview` | `wrangler versions upload --preview-alias pr-` | **A preview takes no production traffic.** `versions upload` uploads the version and gives it its own URL; it never moves the live routes, which a plain `deploy` would. The alias is the pull request number, so the link in the comment is stable across pushes. A branch name isn't: it changes, and it isn't always URL-safe. #### Validating a pull request without publishing it A preview still runs the pull request's code with the Worker's real bindings. For a Worker whose bindings reach data an unreviewed branch shouldn't run against (a private R2 bucket, a production database), don't preview: dry-run the pull request instead. ```yaml dry-run: ${{ github.event_name == 'pull_request' }} ``` On this target a dry run is Wrangler's own `wrangler deploy --dry-run`: it bundles the Worker and validates its configuration, uploads nothing, and calls no API, so it needs **no credentials**. A fork's pull request, or a repository whose deploy token doesn't exist yet, can still prove the Worker builds. A dry run that doesn't bundle fails the job. #### A binding is only real if Wrangler prints it `cloudflare-verify-config` (on by default) runs that same dry run before every publish and refuses to publish when Wrangler reports configuration it won't apply: - **an unexpected field.** A misspelled `[[r2_bucket]]` is only a *warning*: Wrangler exits 0 and deploys a Worker with no bucket, and nothing fails until a request needs it; - **a binding an `--env` deploy doesn't inherit**, which Wrangler also only warns about. The offending lines are printed. It costs one extra bundle per run; set `cloudflare-verify-config: false` to publish anyway. Leave `cloudflare-main` empty for an assets-only Worker, which is the shape that serves files straight from the edge with no cold start, no code in the request path, and asset requests that aren't billed as invocations. Set it to your entry point for a Worker that runs code, and add `cloudflare-build-command` if that code needs bundling first. Wrangler is pinned (`cloudflare-wrangler-version`, 4.114.0 by default), because the tool that publishes to production isn't a floating dependency. The action installs Node 24 for it: Wrangler 4 declares `engines.node >= 22`, and on 20 it installs cleanly and then refuses to run. ### `azure-functions-zip` ```yaml permissions: { contents: read, id-token: write, pull-requests: write } jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7.0.1 - uses: actions/setup-dotnet@v6 with: { dotnet-version: '9.0.x' } - run: dotnet publish -c Release -f net9.0 -o publish - run: cd publish && zip -r -q ../package.zip . # the CONTENTS, dotfiles included - uses: MagmaMoose/tremvok@v2 with: target: azure-functions-zip artifact-path: package.zip azure-client-id: ${{ vars.AZURE_CLIENT_ID }} azure-tenant-id: ${{ vars.AZURE_TENANT_ID }} azure-subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }} functions-app-name: ${{ vars.FUNCTIONS_APP_NAME }} functions-resource-group: ${{ vars.FUNCTIONS_RESOURCE_GROUP }} ``` **No publish profile.** The Azure quickstarts hand you one, and it is a long-lived file carrying the deployment rights of the whole site with nothing tying it to a repository. `azure-client-id` is the alternative and the same argument as `aws-role-to-assume`: an Entra ID app registration with a **federated credential** naming this repository and ref, a session minted per run from the run's own OIDC token, and nothing at rest. That is what `id-token: write` is for. Create the credential against `repo:/:ref:refs/heads/main` (or an environment), and give the service principal `Contributor` on the Function App's resource group — or `Website Contributor`, which is narrower and enough. A caller who would rather run `azure/login` in an earlier step can: leave `azure-client-id` empty and the action uses the session already on the runner. **Zip the contents of the publish directory, not the directory.** `cd publish && zip -r -q ../package.zip .` — because `zip -r package.zip publish` nests everything one level down and `zip -r ../package.zip *` silently skips dotfiles. The worker reads `functions.metadata` and loads its extensions from `.azurefunctions/`, both of which must be at the archive root. Get this wrong and the package deploys perfectly cleanly and then serves nothing: no error, no log line, a 404 on every route. Tremvok refuses such a package rather than letting you discover it in production. **Pin the runtime to `net9.0`.** `DOTNET-ISOLATED|10.0` is offered by the platform and accepted by `az functionapp create`, and a Linux Consumption app on it never starts — the site and its SCM endpoint both return 503, with no log output at all. 9.0 started first try with an identical package. **The exit code is not evidence, and neither is platform state.** `az functionapp deployment source config-zip` has been observed printing `ERROR: Operation returned an invalid status 'Bad Request'` and exiting non-zero over a deploy that *succeeded*. So a non-zero exit is not taken at face value: Tremvok asks the platform whether `WEBSITE_RUN_FROM_PACKAGE` actually moved, and fails only if it did not. Nor does it trust the resource: an `azurerm_linux_function_app` reports `state: Running` and `availabilityState: Normal` while returning 503. After publishing, the app has to **answer**, and the run fails if it never does. Any HTTP status counts, including the 404 a Function App returns at its root when its only trigger is at `/api/`; a connection failure and a 503 do not. A freshly created Consumption app 503s from both the site and its SCM endpoint until content is first published, so a first deploy retries through that rather than failing on it — `functions-ready-attempts` × `functions-ready-delay` is the ceiling, five minutes by default. `verify-url` sits on top of that and is where you assert what a particular route *does*: for a webhook receiver, an unsigned request getting `401` is the check worth having — and it needs `verify-method: POST`. The trigger binds POST and nothing else, so a GET reaches no function and Azure answers `404`, which is also what a package containing no functions returns. Asserting `POST` → `401` is what distinguishes a working deploy from a broken one; a GET against such a route cannot. **A pull request publishes nothing,** unless `functions-slot` is set. A slot is Azure's only destination that does not take production traffic, and a Linux Consumption plan has no slots, so on Consumption a preview validates the package and stops, saying why. On Premium or Dedicated, set `functions-slot` and previews go to the slot. ### `azure-apim-policy` Which Azure target fits a job is its own page: [a Function or API Management?](azure-functions-or-api-management.md) ```yaml permissions: { contents: read, id-token: write, pull-requests: write } jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7.0.1 - uses: MagmaMoose/tremvok@v2 with: target: azure-apim-policy artifact-path: apim/webhook # api.xml and .xml apim-service-name: ${{ vars.APIM_SERVICE_NAME }} apim-resource-group: ${{ vars.APIM_RESOURCE_GROUP }} apim-api-id: webhook azure-client-id: ${{ vars.AZURE_CLIENT_ID }} azure-tenant-id: ${{ vars.AZURE_TENANT_ID }} azure-subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }} verify-url: https://example.azure-api.net/webhook/receive verify-method: POST verify-status: '401' ``` **The API is infrastructure; the policy is behaviour.** Create the instance, the API and its operations with your infrastructure code. This target publishes the documents in `artifact-path`: `api.xml` to the API scope and `.xml` to each operation. A document named after an operation the API does not have is refused before anything is published, rather than creating an operation nobody declared. Keep a policy published here out of your infrastructure code, or the two will overwrite each other. **The same sign-in as `azure-functions-zip`**, and the same federated credential. The service principal needs `API Management Service Contributor` on the instance, or a custom role with read on the service, its APIs and operations, and write on `Microsoft.ApiManagement/service/apis/policies` and `Microsoft.ApiManagement/service/apis/operations/policies`. **All or nothing.** API Management compiles a policy, the XML and every C# expression in it, only when it is published; there is no dry run. So Tremvok reads each scope's current policy first, and if any document is refused it puts back the scopes it had already replaced (or clears those that had none) and fails, naming the document and quoting API Management's reason. **`rawxml` by default.** Write expressions the way the portal shows them, quotes and angle brackets unescaped. Set `apim-policy-format: xml` for documents written as strict XML. **Verify the behaviour, not the publish.** An accepted policy is live on the gateway within seconds, so the publish proves little. Assert what the route does: for a webhook receiver, an unsigned `POST` answering `401`. It needs `verify-method: POST`, because an operation that binds POST answers a GET with `404` whatever its policy says. **A pull request publishes nothing.** A policy's only destination that takes no production traffic is an API revision, which this target does not create. A preview checks the documents and stops, saying so. ### `gitops-pr` For a service a GitOps controller deploys: Flux or Argo CD applies a kustomize overlay from Git, and what changes an environment is a commit to that overlay. This target makes that commit a pull request, one environment at a time, instead of letting image automation push tags to the branch the cluster reads. ```yaml on: release: { types: [published] } push: branches: [main] paths: ['k8s/overlays/acc/**', 'k8s/overlays/prd/**'] permissions: { contents: read } jobs: deploy: runs-on: ubuntu-latest steps: - id: app-token uses: actions/create-github-app-token@v2 with: app-id: ${{ vars.DEPLOY_APP_ID }} private-key: ${{ secrets.DEPLOY_APP_PRIVATE_KEY }} - uses: MagmaMoose/tremvok@v2 with: target: gitops-pr mode: deploy gitops-overlays: | k8s/overlays/acc k8s/overlays/prd gitops-images: ghcr.io/acme/app auth-token: ${{ steps.app-token.outputs.token }} ``` **A release opens the first pull request; a merge opens the next.** On `release: published` it moves every image in `gitops-images` to the release's tag in the first overlay, on a branch of its own (`deploy/acc/v1.2.3`), and opens a pull request. When that merges, the push starts the workflow again: the target finds the merged pull request, reads what it changed in the `acc` overlay, and opens exactly that for `prd`. So `prd` only ever gets a build `acc` ran, and a tag a reviewer changed on the branch is the one that travels. Prereleases are skipped unless `gitops-prereleases: true`, and `gitops-tag` deploys a tag by hand from `workflow_dispatch`. **An App token, not GITHUB_TOKEN.** A pull request opened with GITHUB_TOKEN starts no workflow, so its required checks never report and it can never merge. The App needs contents and pull requests write. Its commits are made through the contents API, so they are signed, which a signed-commits rule on the base branch requires. **Only the tag line changes.** The value on each entry's `newTag:` line is rewritten and nothing else, so a Flux `# {"$imagepolicy": ...}` marker, comments and blank lines survive and the diff is one line per image. An entry is matched by `newName` where it has one, otherwise `name`. A digest-pinned entry, one with no `newTag`, and a flow-style entry are refused rather than half-edited. **One open deploy PR per overlay.** A newer tag supersedes the open one (closed, branch deleted), a re-run refreshes it, an overlay that already runs the tag gets none, and an overlay is never moved backwards: if `prd` runs something newer, or a pull request for a newer tag is already open, nothing is opened. **Release candidates.** With `gitops-prereleases: true` a prerelease travels every overlay like a stable release. `gitops-prereleases-until: acc` stops it at acc instead. When the candidate is signed off and released as its stable version (Diatreme's `promote-from` releases `v1.4.0-rc.2` as `v1.4.0`, the same image), the stable release finds acc already running its candidate and opens the deploy PR for prd directly, so production runs `v1.4.0` and acc is not deployed twice. A stable release whose candidate acc does not run starts at acc as usual, so prd only ever gets what acc ran. Tags compare by SemVer: `v1.4.0` is newer than `v1.4.0-rc.2`. **Turn the image automation off first.** An `ImageUpdateAutomation` writing the same overlay commits the tag to the branch and leaves the deploy PR with nothing in it. And if the repository's release workflow also runs on push, give it `paths-ignore` for the overlays: merging a deploy PR must not cut a release. Diatreme's `deploy-paths` refuses such a release before it tags anything, and skips the image build on a pull request that only moves tags. **Set `mode: deploy`.** `auto` reads a push to anything but the default branch as a mistake, and the overlays' branch is often not the default one (`gitops-base: master` in a repository whose default is `dev`). **Verify on the merge, not on the pull request.** Opening a pull request deploys nothing, so there is nothing to request yet. The run a merge starts is the one where `verify-url` can ask the environment it deployed to. A pull request run deploys nothing and says so. #### Preview environments by label Flux Operator runs one preview environment per label: a `ResourceSetInputProvider` of type `GitHubPullRequest` with `filter.labels` and `filter.limit: 1` hands a `ResourceSet` the open pull request carrying the label, and the environment follows it. When two open pull requests carry the label it takes the newest and says nothing, so a second pull request takes the environment from the first without either author knowing. `gitops-preview-labels` makes each label a claim: the first pull request to take it holds it, and one that takes it later loses the label again, with a comment naming the holder. ```yaml on: pull_request: types: [labeled, unlabeled, closed] permissions: contents: read pull-requests: write concurrency: group: preview-claim-${{ github.event.label.name || github.event.pull_request.number }} queue: max jobs: claim: runs-on: ubuntu-latest steps: - uses: MagmaMoose/tremvok@v2 with: target: gitops-pr gitops-preview-labels: | deploy/preview-1 deploy/preview-2 gitops-preview-urls: | {"deploy/preview-1": "https://preview-1.example.com", "deploy/preview-2": "https://preview-2.example.com"} ``` And on the cluster, one provider per label: ```yaml apiVersion: fluxcd.controlplane.io/v1 kind: ResourceSetInputProvider metadata: name: app-preview-1 namespace: app-preview spec: type: GitHubPullRequest url: https://github.com/org/app secretRef: name: github-auth filter: labels: ['deploy/preview-1'] limit: 1 ``` **The first label on wins.** Every open pull request carrying the label is a claim, ranked by when its label last went on, from its issue events. The holder gets a comment saying it holds the environment, with its URL when `gitops-preview-urls` names one. Every other claim loses the label and gets a comment: *deploy/preview-1 is in use by #12. Remove it there first.* Two pull requests labelled at once end the same way in both runs, because both read the same events. The controller reads the pull requests on its own schedule (`fluxcd.controlplane.io/reconcileEvery`, ten minutes by default), so a refused label is normally gone before it looks. **Each run settles the whole label**, not only its own pull request, so a run that never happened leaves nothing unsettled for the next one. The concurrency group runs a label's events one after another; `queue: max` keeps every waiting run, where the default lets a third event cancel the one waiting. A `closed` event carries no label, so it queues per pull request. **Taking the label off, or closing the pull request, releases it.** The holder's comment then says the environment was released. Closing also takes the label off, so a pull request reopened later does not take the environment back: label it again. **A refused claim is a green run.** The job did what it is for. `gitops-preview-result` says what became of this pull request's claim: `claimed`, `refused`, `released` or `ignored`. A comment that cannot be posted only warns; a label that cannot be taken off fails the run, because the controller would still deploy that pull request. **`pull-requests: write` is the whole grant.** The open pull requests are listed through the pulls API, so GITHUB_TOKEN with that permission will do. An App token works too; a label it takes off starts the workflow again, and that run reads the comment, sees the pull request never held the label, and changes nothing. **Nothing is deployed.** The controller deploys; the run only takes labels off and comments, as any gitops-pr pull request run deploys nothing. A pull request from a fork is skipped like every fork run, because its token cannot write. `dry-run: true` reports what it would do and writes nothing. ### `s3-cloudfront` and `lambda-zip` See [`examples/`](https://github.com/MagmaMoose/tremvok/tree/main/examples). Both need `id-token: write` for the role, and `pull-requests: write` for the sticky preview comment. ### `terragrunt` ```yaml on: pull_request: pull_request_review: { types: [submitted, dismissed] } push: { branches: [main], paths: ['terraform/**'] } schedule: [{ cron: '0 5 * * 1-5' }] # the weekday drift run permissions: contents: read id-token: write pull-requests: write checks: write # the check run that makes apply-before-merge enforceable ``` An independent pull-request approval is the apply authorisation. Approving applies the stacks, and the check run turns green once they are applied. `terragrunt-apply-operators` names who may force one by hand; empty means nobody, so that path fails closed. **Approving is what applies, and the run has to be the approval.** A `pull_request` run that finds an approval already standing plans and reports rather than applying it: the approval was given for the commit it was given for, and a commit pushed after it has not been reviewed. The check run then reads `Approved, but not applied for this commit`. Dismiss the approval and re-approve to apply the commit in front of you. This is what `pull_request_review` is doing in the triggers above, and a workflow without it never applies at all. A review that is a comment or a change request is not an approval either, so it plans. **No AWS credential is required.** Terragrunt takes its credentials from the backend and provider blocks in your own configuration, so an estate on Azure, GCP or a private cloud runs without `aws-role-to-assume` and without `id-token: write`; drop both from the block above if nothing in the run reaches AWS. [Per-stack state credentials](#per-stack-state-credentials) below is how a state-backend key reaches one stack and not the others. The gate is the action's own (`scripts/approval-gate.sh`), so it needs no GitHub `environment:`. Add an `environment:` to your job only if you want what an environment adds beyond the gate: a wait timer, or secrets scoped to it. #### Cancelling a plan without stranding a state lock A caller usually cancels the previous run when a newer push or review arrives (`cancel-in-progress`). A cancelled `tofu` can be killed before it releases the state lock, and a stranded lock fails every later run on that stack, each after waiting out its lock timeout, until somebody force-unlocks it by hand. One stack's lock then fails every pull request that plans that stack, whatever the pull request changes. So a plan that a newer event cancels does not take the lock. `terragrunt-plan-lock: auto` (the default) plans with `-lock=false` on a `pull_request` run and on a `pull_request_review` that does not approve, and both only ever plan. Everything that can apply keeps the lock: an approving review, a push, a schedule and a manual run. An apply always locks. `always` puts the lock back on every plan. What no lock costs: a plan that reads state while another run applies can show a diff the apply is halfway through making. It is a pull-request comment, redone on the next push, and never the plan that is applied, because an apply re-plans or applies a saved plan that `tofu` refuses when the state has moved. Keep not cancelling an apply. Only a plan can go without the lock. If a lock is already stranded, the failing job's log names it (`ID`, `Path`, `Who`, `Created`). Check that nothing is running, then release it from that stack's backend with `tofu force-unlock `. The ID is also the blob lease ID on `azurerm`. #### Letting a merge apply what it merged Off by default. A push to the default branch plans and applies nothing unless you ask for more: ```yaml with: target: terragrunt terragrunt-apply-on-merge: 'true' ``` A push event carries no pull request, and the approval that authorises an apply belongs to the pull request the commit was merged from. With this on, the run resolves that pull request from the commit (`GET /repos/{repo}/commits/{sha}/pulls`, so squash, merge-commit and rebase merges all resolve) and reads its reviews. Three outcomes, kept distinct on purpose: | On the default branch, with apply-on-merge on | What happens | | --- | --- | | Merged from a pull request that had an independent approval | the affected stacks are applied, and the plan comment on that pull request is rewritten to the result | | Merged without one, or pushed directly | plans and applies nothing, commenting on the merged pull request when there is one to comment on. The run exits `0` and the check run is `neutral` / `Planned; not applied` | | The API could not be read, and there were pending changes | nothing is applied and the run **fails**, with a `failure` check run published first. An API outage must never read as "nobody approved" | Where several merged pull requests are associated with one commit, the one whose base branch is the branch that was pushed wins; among the rest, the oldest merge does. Neither unreadable answer — the review list or the commit-to-pull-request lookup — refuses unless there was something to apply, so a merge where every stack plans clean is not turned red by an API blip. Both still warn, so a token missing `pull-requests: read` does not stay invisible until the first merge that changes something. An unapproved merge is reported rather than failed: it is a branch-protection matter, not a broken build, and turning the default branch red does not fix it while leaving the stacks unapplied and invisible would. The scheduled drift run keeps reporting them, and `terragrunt-apply: force` applies them by hand. `terragrunt-apply-on-merge` is deliberately not a value of `terragrunt-apply`. That input answers "who may authorise an apply?"; this one answers "should a merge commit apply at all?". With it on, the path needs `pull-requests: read` on the token, which the `pull-requests: write` above already covers. #### When there is nobody to approve An independent approval needs a second person. In a repository with one maintainer nobody can give it, so `terragrunt-apply-on-merge: 'true'` never applies anything. `without-approval` makes the merge the authorisation: ```yaml on: pull_request: push: { branches: [main], paths: ['terraform/**'] } schedule: [{ cron: '0 5 * * 1-5' }] workflow_dispatch: inputs: apply: description: 'Stacks to plan and apply by hand. Empty plans everything and applies nothing.' type: string default: '' jobs: terragrunt: runs-on: ubuntu-latest steps: - uses: actions/checkout@ # v7.0.1 with: { fetch-depth: 0 } - uses: MagmaMoose/tremvok@v2 with: target: terragrunt checkout: false terragrunt-apply-on-merge: without-approval # Only the stacks a merge changed. A module change is planned on its pull request. terragrunt-scope: ${{ github.event_name == 'push' && 'direct' || 'auto' }} terragrunt-hold-destroys: 'true' # The way past both: somebody read the plan and names what to apply. terragrunt-stacks: ${{ inputs.apply }} terragrunt-apply: ${{ inputs.apply && 'force' || 'auto' }} terragrunt-apply-operators: your-login ``` A pull request plans and comments as usual, and its check run is a `success` titled `Planned; nothing applied until it merges`, because nothing has to happen first. A merge from a pull request applies, and the plan comment on that pull request is rewritten to the result. A direct push still plans and applies nothing. An unreadable commit-to-pull-request lookup with changes pending still fails the run, because the run cannot tell the commit came from a pull request. The merge is then the only review, and that is what the other inputs are for. Anyone who can merge can apply, so: - **`terragrunt-scope: direct` on the push** applies only the stacks the merge changed. A module or a shared `root.hcl` reaches stacks nobody named, and whatever was pending in them would go with it. So its pull request plans the stacks it reaches, its merge applies none of them, and the run warns with the path. A `.md` file counts for nothing. - **`terragrunt-hold-destroys`** stops the run before anything is applied when any stack's saved plan destroys, replaces or forgets something, or cannot be read back. The check run is a `failure` titled `Apply held: a plan destroys`. If state moves after that check, a stack that still has changes fails rather than applying a plan nobody read, and the others carry on. It cannot be combined with `terragrunt-rolling`, which plans each unit on its own. - **`terragrunt-plan-pin: plan.pin`** lets a change say what its plan does, in a file the reviewer reads in the diff. A stack the change reached directly is compared with the first line of its `plan.pin` that is not blank and not a `#` comment: `Plan: 0 to add, 0 to change, 1 to destroy.` or `No changes.`, counted from the saved plan. The plan comment shows whether each pinned stack matches. A plan that differs fails the pull request's check, and on the merge applies nothing and fails the run, so a change whose state moved on since it was reviewed never lands. A stack whose plan matches is past the hold, because its pin declared what it destroys, and applies that plan or nothing. A module or a shared file holds no stack to its pin, and neither does a scheduled run. - **`terragrunt-stacks` with `terragrunt-apply: force`** is the way past all three, by an actor named in `terragrunt-apply-operators`. Each path must be a stack the pipeline runs, so it cannot reach one `terragrunt-exclude` keeps out. Put a GitHub `environment:` on the job if only some branches may do this. This is not as strong as an approval, and it is not meant to look like one. With a second person available, use `'true'`. #### Which stacks a change plans A stack is a directory holding `terragrunt.hcl`. On a pull request or a push, the changed files decide which of them run: | The change | The stacks it plans | | --- | --- | | A file inside a stack | that stack, however deep the file sits inside it | | A file above the stacks, such as a shared `root.hcl` | every stack beneath that file's own directory, because every one of them includes it through `find_in_parent_folders` | | A file directly in `terragrunt-root` | every stack, for the same reason | | A file under `modules/` (or another excluded directory of shared code) | every stack beneath the nearest directory above it that holds any | | A file inside a stack named in `terragrunt-exclude` | none: that stack is applied by hand, and it owns everything inside it | | A file under a directory named in `terragrunt-exclude` by a path, such as `terraform/aws` | none, for the same reason, however many stacks it holds | | A file outside `terragrunt-root` | none | A module widens on purpose. Which stacks use it cannot be known without evaluating the HCL, and the narrow answer, nothing, publishes a green "No Terraform stacks affected" while the change lands unplanned. Planning is read-only and a stack the module does not reach plans clean, so the wide answer costs time, not correctness. It stops at the first directory above the module that holds stacks, so `terraform/eurofiber/_modules/x` never plans `terraform/azure`. A stack you exclude by name, `edge-gateway-firewall` in `terragrunt-exclude` for a directory of that name, is the opposite case. A change inside it is not shared configuration: it belongs to a stack the pipeline must not touch, so it plans nothing at all, rather than being widened to the stacks beside it and applied from the pull request's base on approval. A directory excluded only because it sits under an excluded one (`modules/x`) is still shared code. Everything above is per changed path and the results are merged, so one pull request that edits a shared root and one stack plans that whole subtree once. #### Rolling a change through a cluster, one node at a time A plan is applied in one go, and for most stacks that is what you want. It is not what you want when the change restarts what it touches. Resizing a cluster's VMs is the case that wrote this: the provider powers each VM off to change its CPU count, one apply of the whole plan does that to every node at the same moment, and the cluster, with everything on it, goes down with them. `terragrunt-rolling` names the stacks to roll and, for each, the `for_each` or `count` blocks whose instances are the units: ```yaml with: target: terragrunt terragrunt-rolling: | */k3s-cluster module.node vcd_independent_disk.longhorn terragrunt-rolling-pause: '600' ``` When the plan to be applied changes two or more units, the apply: 1. takes the units in plan order, and plans each on its own, with a `-target` for its key under every listed address (`module.node["worker-0"]` and `vcd_independent_disk.longhorn["worker-0"]`); 2. refuses that plan, before any of it is applied, when it changes another unit; 3. applies it, then waits `terragrunt-rolling-pause` seconds (300 by default) before planning the next unit, so the last one is back before another goes down; 4. ends with a full plan, which applies whatever no unit holds (a shared network, say) and proves every unit landed. A plan that changes one unit, or none, applies the saved plan exactly as before. **List every per-unit block, not just the main one.** tofu plans every instance of a resource a target depends on, unless that resource is itself targeted: a node targeted as `module.node["cp"]` alone pulls in every other node's disk resize, and that is the outage again. Instances of listed addresses that share a key are one unit, so a node and its disk roll together, and a unit is targeted under every listed address even where it has no instance (a control-plane node with no data disk), because a target that names nothing still keeps the other instances out. A change outside every unit that is keyed like another unit, `disk["worker-1"]` in `worker-0`'s plan, is taken for a per-unit block nobody listed, and refused. What it costs: - **Time.** The run waits the pause before every unit after the first: ten minutes over six nodes is fifty minutes. `terragrunt-timeout` is per command, so it does not cut a long roll short, but the job's own `timeout-minutes` has to allow for it. - **What lands is not the saved plan.** A plan file cannot be applied in part, so each unit is planned again, on its own, just before it is applied. The saved plan decides which units roll. - **The pause is a wait, not a health check.** The roll does not know whether a node came back. Pick a pause long enough for a node to rejoin and for replicated storage to catch up. A refused or failed unit fails the run and stops the roll there; the units before it stay applied. Fix the cause and apply again: units already applied plan clean and are skipped without a pause. #### Failing fast on an unreachable endpoint Terragrunt buffers plan output to a file, so a state backend or provider API the runner cannot reach is not an error: it is a silent wait until `terragrunt-timeout` with an empty log. `terragrunt-preflight-urls` probes each URL once, with an 8-second timeout, before the first plan: ```yaml with: target: terragrunt # A repository variable, so an unset one probes nothing and the block is safe to copy. terragrunt-preflight-urls: ${{ vars.TERRAGRUNT_PREFLIGHT_URLS }} ``` Any HTTP answer passes, `401` and `403` included: an unauthenticated probe of a credentialed endpoint is supposed to be refused, and being refused proves something is there. Only a curl code of `000` fails, which is DNS, connection refused, a connect timeout or a TLS failure. A `5xx` warns and passes, so a transient `503` cannot make this a flake. When something is unreachable the step prints the runner's egress IP, which is the fact you need next if the endpoint is IP-allowlisted. It proves reachability, not authorisation. A passing `403` does not mean your credential works. Blank lines and `#` comments are ignored, and these URLs are printed into the run log, so put nothing secret in them. A URL carrying userinfo (`https://user:password@host/`) is refused outright, and the refusal names the line by its index and shows the URL with the userinfo replaced, rather than echoing the line. Empty (the default) probes nothing. #### Planning a named pull request by hand `terragrunt-pull-request` points a manual run at one pull request: its reviews are what the approval gate reads, its thread is where the plan comment goes, and its head commit is what the check run is published against. ```yaml on: workflow_dispatch: inputs: pull_request: description: 'Pull request number to plan. Empty plans the default branch.' type: string default: '' jobs: terragrunt: runs-on: ubuntu-latest steps: - uses: actions/checkout@ # v7.0.1 with: fetch-depth: 0 # GitHub's merge of the pull request into its base: what lands on the default # branch if it merges. Empty falls back to the ref the run started from. ref: ${{ inputs.pull_request && format('refs/pull/{0}/merge', inputs.pull_request) || '' }} - uses: MagmaMoose/tremvok@v2 with: target: terragrunt # Not optional here. Without it the action checks the workflow ref out again and # the merge tree is gone. checkout: false terragrunt-pull-request: ${{ inputs.pull_request }} ``` Checking out the right tree is yours, not Tremvok's: the action never fetches a merge ref, it plans whatever is on disk. When the named pull request's head commit is not in that tree the run warns and carries on, because `checkout: false` with a partial tree is a legitimate choice. Two things fall out of this shape. You dispatch from the default branch and name the pull request by number, so the "a manual run must start from main" rule still passes with no exception. And `refs/pull//merge` does not exist while the pull request has conflicts, so `actions/checkout` fails with git's own message before Tremvok runs at all. `terragrunt-scope: auto` means the stacks that pull request touches whenever a pull request is in scope, however it got there. `all` stays legal: plan the whole estate, gate on that pull request's approval, comment on that pull request. A fork pull request is refused on this path, exactly as the automatic one refuses fork code before it reaches a deploy credential. ### Credentials for the providers, which are not the state backend's The most confusing failure this target has, and the one worth setting up before the first run. A terragrunt run needs more than one credential, and they come from different places: - **The state backend's**, which `terragrunt-stack-env` supplies per stack — an `ARM_ACCESS_KEY`, a role, a key file. See the section below. - **Every provider's**, resolved by that provider's own chain, which nothing in the workflow mentions. Supply the first and not the second and the run does not fail early or clearly. `init` reads and writes state perfectly well, the plan starts, and then every stack dies inside a provider: ```text Error: unable to build authorizer for Resource Manager API: could not configure AzureCli Authorizer: tenant ID was not specified and the default tenant ID could not be determined: obtaining tenant ID: obtaining account details: running Azure CLI: exit status 1: ERROR: Please run 'az login' to setup account. with provider["registry.opentofu.org/hashicorp/azurerm"], on provider.tf line 25, in provider "azurerm": ``` Twenty times over, pointing at a `provider.tf` a `generate` block wrote and nobody has opened. That reads as a broken runner. It is a credential nobody wired. #### Azure The same three inputs as `azure-functions-zip`, and the same federated credential: ```yaml permissions: { contents: read, pull-requests: write, checks: write, id-token: write } - uses: MagmaMoose/tremvok@v2 with: target: terragrunt azure-client-id: ${{ vars.AZURE_CLIENT_ID }} azure-tenant-id: ${{ vars.AZURE_TENANT_ID }} azure-subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }} ``` The action signs in with this run's OIDC token before the first plan, and `provider "azurerm"` with no explicit auth picks that session up from its default chain. Give the app registration a federated credential for each subject the workflow runs under — `repo:/:pull_request` for the plan on a pull request, and `repo:/:ref:refs/heads/` for the apply, the post-merge run and the schedule — with audience `api://AzureADTokenExchange`. **On GitHub Enterprise Cloud with data residency the issuer is not `https://token.actions.githubusercontent.com`.** It is `https://token.actions..ghe.com`. Read `/.well-known/openid-configuration` at that host and use the `issuer` it returns; a federated credential built on the wrong one fails with a message that blames the token rather than the issuer. #### AWS `aws-role-to-assume` applies to this target too, and has since the target existed — the step is gated on the input, not on a target, so nothing extra is needed: ```yaml - uses: MagmaMoose/tremvok@v2 with: target: terragrunt aws-role-to-assume: arn:aws:iam::123456789012:role/tremvok-terragrunt aws-region: eu-west-1 ``` The assumed-role session is exported into the environment, so both the S3 backend and the `aws` provider find it in the default chain — one credential covers both, unlike Azure. #### Google Cloud ```yaml - uses: MagmaMoose/tremvok@v2 with: target: terragrunt gcp-workload-identity-provider: projects/123456/locations/global/workloadIdentityPools/github/providers/tremvok gcp-service-account: tremvok@my-project.iam.gserviceaccount.com # optional gcp-project-id: my-project # optional ``` The full **provider** resource name, not the pool — a pool name is refused before any call is made, because Google answers it with a 400 about an invalid audience that names nothing useful. The action mints the run's OIDC token, writes it and a small `external_account` credential configuration into `RUNNER_TEMP` at 0600, and exports `GOOGLE_APPLICATION_CREDENTIALS`. The Terraform `google` provider reads that variable like every other Google client, and a GCS backend uses the same credentials. `gcp-service-account` is optional. Leave it empty when the IAM bindings name the pool's `principalSet` directly; set it, and that principalSet needs `roles/iam.workloadIdentityUser` on the service account. Both halves are proved before the run continues, because they fail alike from inside Terraform and have different fixes: an STS exchange that is refused means the pool provider's issuer or attribute condition does not match this repository or ref, and an impersonation that is refused means it does match and the `workloadIdentityUser` binding is missing. The error names which. #### Anything else Sign in during an earlier step, or hand the credential to the stacks that need it through `terragrunt-stack-env`. The action does not care which; it checks that *something* is there. #### The check that says so in one line `terragrunt-credential-preflight` reads the `provider` blocks of every discovered stack, and of every parent directory up to `terragrunt-root` so a shared `root.hcl` counts, and asks whether this runner holds a credential for each cloud they name. On `auto`, the default, a missing one fails the run before the first plan with the cloud, the stacks and the fix: ```text ## Terragrunt — a provider has no credential ### azure — 19 stack(s) set azure-client-id, azure-tenant-id and azure-subscription-id (the action signs in with this run's OIDC token), run azure/login in an earlier step, or hand the stack ARM_CLIENT_ID and a secret through terragrunt-stack-env. ARM_ACCESS_KEY is the state backend's credential and does not configure the provider. - `terraform/azure/non-prod/westerneurope/aks` (provider "azurerm") ``` It knows azurerm/azuread/azapi, aws, google/google-beta and vcd, and passes over a provider it does not recognise in silence rather than guessing. A provider block that configures its own authentication — `client_id`, `credentials`, `api_token` and the rest — is not checked, because that stack has answered the question itself. It proves a credential is **present**, never that it is valid or that it reaches the subscription, project or account the stack names — the same line `terragrunt-preflight-urls` draws between reachable and authorised. `warn` annotates and plans anyway; `off` checks nothing. ### Per-stack state credentials If your production state lives in a different storage account from the rest, which is a deliberate blast-radius boundary rather than an accident, one credential can't reach both. `terragrunt-stack-env` applies environment per stack: ```yaml with: target: terragrunt terragrunt-stack-env: | */prd/*|*/prod/* ARM_ACCESS_KEY=${{ secrets.PRD_STATE_KEY }} * ARM_ACCESS_KEY=${{ secrets.STATE_KEY }} ``` One ` KEY=VALUE` per line. The first matching line wins for a given key, so the specific pattern goes above the catch-all, exactly as it would in a `case`. Blank lines and `#` comments are ignored, and a line with a pattern but no assignment fails the run rather than being skipped. The values are secrets, so they're passed to each invocation with `env` rather than exported into the shell: one stack's credential never reaches the next stack's run. The apply gets the same environment the plan got, which matters more than it sounds. A plan that reads state with one credential and an apply that writes it with another is the worst version of this bug, because the plan looks fine. ### `ansible` ```yaml permissions: { contents: read, pull-requests: write } ``` Runner-agnostic on purpose. A fleet reachable only from inside a private network needs a self-hosted runner that sits in it. That's your `runs-on:`, and the action does not check, because the same playbook against reachable hosts is a legitimate use. #### Letting the playbook read its own Vault secrets `vault-addr` and `vault-token` let the action resolve `ansible-*-vault` references. They live in the step's environment, and by default the action removes them before `ansible-playbook` starts: a token scoped to the fields Tremvok reads would otherwise be usable by every task, role and collection in the play, and nobody chose that. `ansible-vault-passthrough: true` chooses it. `VAULT_ADDR`, `VAULT_TOKEN` and `VAULT_NAMESPACE` are then passed to the playbook, so it can read its own secrets from the same Vault instead of having them copied into a second store that quietly stops being rotated. The token is masked. Without both `vault-addr` and `vault-token` set, nothing is passed and the run says so. Nothing to do with ansible-vault the file-encryption tool; that is `ansible-vault-password`. ## An IAM role the workflow can assume For the three targets that can use an AWS role. `s3-cloudfront` and `lambda-zip` need one, and `terragrunt` needs one only when its own backend or providers reach AWS. Tremvok authenticates with this run's GitHub OIDC token; nothing is stored in the repository. The role's trust policy is what decides who may use it. Scope it to the repository **and** the refs that may deploy: ```json { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam:::oidc-provider/token.actions.githubusercontent.com" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "token.actions.githubusercontent.com:aud": "sts.amazonaws.com" }, "StringLike": { "token.actions.githubusercontent.com:sub": "repo:my-org/my-site:ref:refs/heads/main" } } } ``` `StringLike` on `sub` with a `ref:` prefix, not `repo:owner/name:*`. The wildcard form lets a pull request from a branch in the same repository assume a production deploy role. Grant it only what the target needs. For `s3-cloudfront` that's `s3:PutObject`, `s3:DeleteObject`, `s3:ListBucket` on the one bucket, and `cloudfront:CreateInvalidation` on the one distribution. ## Secrets for the ansible target The SSH key and the vault password arrive as repository or organisation secrets, passed as inputs. Tremvok masks each on receipt, writes them to `0600` files under `$RUNNER_TEMP`, and removes them with a trap that fires however the step exits, nothing reaches a command line, where `ps` would show it. ```yaml with: target: ansible ansible-playbook: ansible/site.yml ansible-inventory: ansible/inventory/production ansible-ssh-private-key: ${{ secrets.ANSIBLE_SSH_KEY }} ansible-vault-password: ${{ secrets.ANSIBLE_VAULT_PASSWORD }} ansible-ssh-known-hosts: ${{ secrets.ANSIBLE_KNOWN_HOSTS }} ``` `ansible-ssh-known-hosts` is optional and omitting it disables host-key checking, which the run says out loud. Supply it for anything reachable from a network you do not control. ### Reading them from HashiCorp Vault instead If a secret already lives in Vault, name it by reference rather than copying it into a GitHub secret. A copy is a second thing to rotate, and the failure mode is silent: you rotate in Vault, the copy keeps working, and nobody finds out until it doesn't. ```yaml with: target: ansible ansible-playbook: ansible/site.yml ansible-inventory: ansible/inventory/production vault-addr: https://vault.example.com:8200 vault-token: ${{ secrets.VAULT_TOKEN }} ansible-ssh-private-key-vault: secret/data/team/app#ssh_private_key ``` The reference is `#`. Each `-vault` input is the **alternative** to the literal one, never a supplement: setting `ansible-ssh-private-key` and `ansible-ssh-private-key-vault` together fails rather than quietly preferring one. `ansible-ssh-known-hosts-vault` and `ansible-vault-password-vault` work the same way. !!! note "Two different products called Vault" `vault-addr` and `vault-token` are HashiCorp Vault. `ansible-vault-password` is ansible-vault, the file-encryption tool, and has nothing to do with it. That's why the HashiCorp inputs aren't prefixed `ansible-vault-`: it would read as the wrong one. KV v1 and v2 both work without you saying which: v2 nests the payload one level deeper, and both shapes are tried. If you're on v2 the path needs its `/data/` segment (`secret/data/team/app`, not `secret/team/app`), and a 404 says so. The token needs read on the paths you reference and nothing else. What comes back is masked and written to a `0600` file exactly like a literal secret, on the same single code path, and a failed read fails the run rather than continuing with no key. ## (Optional) The Tremvok API Only needed for deployment history, or for notifications that do not put a webhook URL in every repository. Deploying it is described in [terraform/README.md](https://github.com/MagmaMoose/tremvok/blob/main/terraform/README.md); the short version is that the module needs an artifact bucket, two SSM parameters written by hand, and `allowed_owners` set to the GitHub owners you actually control. Then add `api-url:` to the action and `permissions: id-token: write`. The repository stores nothing. ## Verify it, properly After the first deploy of any new wiring: ```bash curl -si https://your-site/ | head -1 # the site answers ``` and for the API, a **real signed POST**, not a `GET /healthz`. A health check passing proves the function imported; it proves nothing at all about the write path, the table, or the IAM policy. The LocalStack smoke suite exists to make that distinction cheap to test. ### One promotion PR for a suite Use `gitops-suite-images` when apps have independent tags. Set one `gitops-suite-overlay` and the controller's `gitops-base`. A stable branch `/` retains pending images and refreshes the same PR. The action merges the current base into that branch; a merge conflict stops the run instead of resetting pending work. ```yaml - uses: MagmaMoose/tremvok@v2 with: target: gitops-pr mode: deploy auth-token: ${{ steps.token.outputs.token }} gitops-base: main gitops-branch-prefix: chore/promote gitops-suite-overlay: k8s/prd gitops-suite-images: '{"ghcr.io/example/web":"v1.2.0","ghcr.io/example/api":"v3.1.4"}' gitops-suite-repositories: '{"ghcr.io/example/web":"example/web","ghcr.io/example/api":"example/api"}' ``` `gitops-suite-repositories` is optional and creates links to the final selected app releases. Suite mode ignores stale versions per image, preserving a newer pending release even if an older event arrives later. It writes only the `newTag` lines; workload resources stay wherever the overlay references them. The runner needs mikefarah/yq v4, curl and jq. The token needs repository contents and pull requests write. For manual dispatch, configure `gitops-suite-allowed-actors` with GitHub logins. Both `github.actor` and `github.triggering_actor` must match; an empty list denies manual changes. A caller can resolve an identity-provider group into the authorized login list before this step. `gitops-suite-allow-downgrade: true` only works on an authorized manual dispatch. Dry runs produce a plan without a branch, commit or PR. --- # Troubleshooting Source: docs/troubleshooting.md URL: https://docs.magmamoose.com/tremvok/troubleshooting/ Every entry here is an error the action or the API actually emits. The message is quoted as it appears in the log. ## Inputs and setup ### `these inputs do not apply to target: ` The run passed an input belonging to a different target. The log names each one and where it belongs, and lists all of them at once so you fix them in one pass rather than one per run. This fires before the checkout, so it costs a couple of seconds. Check the "Applies to" column in the [action reference](action-reference.md), or drop the input. There's one thing this can't catch: an input set explicitly to the value it already defaults to. GitHub gives a composite action no way to tell "unset" from "set to the default". An input holding its default changes nothing, so the blind spot is harmless. ### `unknown target ''` `target` accepts `github-pages`, `cloudflare-docs`, `cloudflare-workers`, `s3-cloudfront`, `lambda-zip`, `terragrunt`, `ansible`, `azure-functions-zip`, `azure-apim-policy` or `gitops-pr`. The message lists them. There's no default, on purpose: guessing `github-pages` would silently build a site for someone who meant to deploy a Lambda. ### `Tremvok skipped: this pull request comes from a fork` Working as designed. A fork can't read your secrets, so the credential is empty and the deploy would fail with an authentication error that looks like a broken credential rather than a policy doing its job. The run reports a skip with the reason instead. `allow-fork-preview: true` exists and is almost always wrong: it converts an honest skip into an auth error. ### `Tremvok skipped: no AWS credential is available for target: ` Only `s3-cloudfront` and `lambda-zip` raise this, the two targets that call AWS themselves. Set `aws-role-to-assume`, or configure credentials in an earlier step. No other target sees it. `github-pages`, `cloudflare-workers` and `ansible` publish somewhere else, and `terragrunt` takes its credentials from the backend and provider blocks in your own configuration, which may name AWS, Azure, GCP, a private cloud, or several in one run. Skipping any of them for a missing AWS credential skips a run that never needed one. If a terragrunt run does need AWS and has none, terragrunt fails in the provider with a message naming it, which is the more useful error. Before this was fixed, a terragrunt run with no `aws-role-to-assume` was skipped outright: every terragrunt step is gated on this skip, so the target quietly did nothing. ### `could not configure AzureCli Authorizer: ... Please run 'az login'` during a terragrunt plan Or `exec: "az": executable file not found in $PATH`, which is the same problem on a runner without the CLI installed. The state backend has a credential and the **provider** does not. They are different credentials from different chains: `terragrunt-stack-env` supplies the first, which is why `init` reads and writes state perfectly well and the failure only arrives once the plan reaches `provider "azurerm"`. An `ARM_ACCESS_KEY` opens one storage account; it cannot configure a provider. Set `azure-client-id`, `azure-tenant-id` and `azure-subscription-id` — the action signs in with this run's OIDC token before the first plan. Or run `azure/login` in an earlier step, or hand the stacks `ARM_CLIENT_ID` and a secret through `terragrunt-stack-env`. See [Setup](setup.md#credentials-for-the-providers-which-are-not-the-state-backends). ### `N stack(s) declare a provider with no credential on this runner` `terragrunt-credential-preflight` caught the failure above before the first plan rather than twenty stacks into it. The summary names the cloud, the stacks and the fix. If it is wrong — the credential is there and the check cannot see it — the useful question is *how* the provider authenticates. A provider block that configures its own authentication is not checked at all, so a stack reading `client_id` from a variable is already exempt. What is left is a chain this action does not know about, and `terragrunt-credential-preflight: warn` is the escape hatch; `off` turns it off entirely. Both are worth a moment's thought first: the error it replaces costs a full plan cycle across every stack to say less. ### `Google STS refused the OIDC token for ` The federation itself, not the permissions. The pool provider's issuer URI or its attribute condition does not match this run. Check the issuer is the one your enterprise actually mints tokens from (on GitHub Enterprise Cloud with data residency that is `https://token.actions..ghe.com`, not `token.actions.githubusercontent.com`), and that the attribute condition allows this repository and ref. The message carries Google's own `error_description` when there is one. ### `the federated identity may not impersonate ` The opposite half: the pool accepted the token and the service account will not be impersonated. Grant the pool's `principalSet` `roles/iam.workloadIdentityUser` on that service account. Or drop `gcp-service-account` entirely and bind the roles to the principalSet, which is one fewer indirection. ### `gcp-workload-identity-provider must be the provider's full resource name` A pool is not a provider. It is `projects//locations/global/workloadIdentityPools//providers/` — the project **number**, not its id. Refused before any call, because Google answers a pool name with a 400 about an invalid audience that names neither the pool nor the provider. ### `terragrunt-credential-preflight must be auto, warn or off` It is an enum, not a boolean. `true` and `false` are refused rather than read as one of them. ### `role-to-assume is set but this job cannot mint an OIDC token` Add `permissions: id-token: write` to the job. Without it, GitHub doesn't hand the runner a token to exchange. ### `STS refused to assume . Check the role's trust policy allows this repository and ref.` The role exists and the token is valid, but the trust policy doesn't match this run. The usual cause is a `sub` condition scoped to a branch the run isn't on. See [Setup](setup.md#an-iam-role-the-workflow-can-assume) for the policy shape, and note the `StringLike` on `sub` should carry a `ref:` prefix rather than `repo:owner/name:*`. ### `build-git-credentials line has no ':' between the username and the token` A line is exactly ` :`. The username is written out rather than guessed, because the forges disagree: `x-access-token` for a GitHub App installation token, `oauth2` for a GitLab one. Every message from this input names the line by its index and its host and stops there. The token is never shown, and neither is the line, because the annotation carrying it is as public as the repository. Count blank lines and `#` comments when you go looking for line ``: the index names the line you typed. ### `build-git-credentials line has a token under 8 characters` Refused rather than used. A real token is never that short, so this is a truncated paste — usually a secret that resolved to nothing because it isn't set on this repository, leaving the line half-formed. Masking a string that short would be worse than not masking it: every occurrence of those few characters in every later line of the log would turn into asterisks. ### `build-git-credentials line starts with a URL, not a host` / `does not start with a host` Write the bare host — `git.example.invalid`, not `https://git.example.invalid/org/repo.git`. The rewrite is built from it, and it has to match the host in the dependency URL exactly or git never applies it. Both refusals name the line by index alone: what's in that field may itself be a credential. ### `build-git-credentials names host twice` Two rewrites for one host, and which one git picks isn't defined, so the credential in use wouldn't be the one you can read off the input. One line per host; if two builds need different tokens for the same host, they need different jobs. ### `GIT_CONFIG_COUNT holds '', which is not a number` Something earlier in the job set `GIT_CONFIG_COUNT` to something git can't read. This step extends that count rather than starting again at 0, so a rewrite an earlier step configured survives; it can't do that against a value it can't parse. Fix or unset the variable. ### The build still can't clone, and nothing was refused The rewrite only fires on an exact host match. Check the host in the line is spelled the same as the host in the dependency URL, and that the token is scoped to the repository being cloned: an installation token reaches only the repositories its installation was given, and the clone fails with git's own `Authentication failed` rather than anything Tremvok prints. ## `target: github-pages` ### `no uv.lock and no docs/requirements.txt — cannot tell how to install MkDocs` Detection looks for `uv.lock` first, then the file named by `pages-requirements`. If your repo has neither, set `pages-toolchain` to `uv` or `pip` explicitly. ### `pages-toolchain must be auto, uv or pip (got '')` The only three values. `auto` is the default and is right almost always: `uv.lock` in the tree is the fact, and a caller restating it in config is one more thing that can disagree with the repo. ### `no mkdocs.yml in — nothing to build` `working-directory` doesn't point at the directory holding `mkdocs.yml`. ### The build passed but nothing was staged for the Pages deploy Expected on a pull request, and there's no input to change it. GitHub Pages has one site and no preview destination, so a run in `mode: preview` (which is what a pull request resolves to) builds and checks without staging an artifact, and `dry-run: true` does the same. The run summary says `staging a Pages artifact: false`; the log says `stage-pages=false`. On a push to the default branch both say true. If a push also staged nothing, check the job summary for a skip: a fork pull request and an unwired repository both report one with a reason. ### `gen-docs-agents: site_name '' gives no Agent Skills name` The skill is named after `site_name`, lowercased, with every run of anything but letters and digits turned into one hyphen, and a `site_name` with no Latin letter or digit in it leaves nothing to name it by. Set `extra.agents.skill.name` to a name of `a-z`, `0-9` and single hyphens. The rest of the agent-readiness step still runs; only the skill is left out. ### The published site has no `/.well-known/agent-skills/index.json` Check that the step ran (`pages-agent-ready`, on by default) and that the site does not already publish its own `/.well-known/agent-skills/`, which the step keeps whole. On `github-pages` the Pages artifact includes dot-directories only while `pages-agent-ready` is on, because `actions/upload-pages-artifact` leaves them out otherwise. On a host shared through the docs router, a site's skill appears in the host's root index within five minutes of its deploy, the time the router keeps what it last read from each site. ## `target: s3-cloudfront` and `target: lambda-zip` ### `artifact-path '' is not a directory` / `is not a file` / `is empty` The build step didn't produce what the deploy expects: a directory for `s3-cloudfront`, a `.zip` for `lambda-zip`. !!! warning "The empty-directory refusal is deliberate" An empty build directory plus `aws s3 sync --delete` empties the live site and exits `0`. The refusal is what stands between a build that quietly produced nothing and an outage. Don't add a flag to override it. ### `Lambda reports CodeSha256 but the artifact is . The function is not running the package this run built.` The update was accepted and the function is serving different code. Usually a concurrent deploy, or an update that targeted a different function or alias. "The API accepted my request" is not "the function runs my code", which is why this check exists. ### `No module named 'pydantic_core._pydantic_core'` on the first request A cross-architecture package. The deploy succeeded because nothing loads the code until a request arrives. `build_api_zip.py --arch` and the module's `architecture` must agree. See [Configuration](configuration.md#terraform-module-variables). Unzipping the package on a macOS laptop and importing it fails the same way, and that one is correct: the builder fetches Linux wheels for the function's architecture. ## `target: cloudflare-workers` ### `CLOUDFLARE_API_TOKEN is required` / `CLOUDFLARE_ACCOUNT_ID is required` The log names the input that supplies each one, `cloudflare-api-token` and `cloudflare-account-id`. Both are checked before anything is installed or built, so a missing secret costs a second rather than a build. The usual cause is a fork pull request, which can't read secrets, and which the preflight skip normally catches first. Mint the token from Cloudflare's "Edit Cloudflare Workers" template rather than a hand-picked permission list, or the first deploy of a custom domain fails on a permission nobody thought to grant. `WRANGLER_VERSION is required` is the same guard: you blanked `cloudflare-wrangler-version`, and the tool that publishes to production is not a floating dependency. ### `artifact-path '' is not a directory` `artifact-path` is the Worker's asset directory for this target, passed to Wrangler as `--assets`. Either the build step didn't run, or it wrote somewhere else. Leave the input empty if the asset directory in your Wrangler config is the one you want. ### `artifact-path '' has no files in it. Refusing to publish an empty asset directory over a site that is currently serving.` The build produced nothing and the deploy would have replaced a working site with it. Same refusal as the S3 target, for the same reason. !!! warning "There is no flag to override this" A build that quietly produced nothing is indistinguishable from a successful one right up until the site is empty. The refusal is the only thing standing between the two. ### `preview mode needs a preview-alias` `mode: preview` uploads a version under an alias, and the alias is what makes that version reachable without touching production. It's `pr-`, resolved from the event, so this means preview mode with no pull request behind it: usually `mode: preview` forced on a push. Let `mode: auto` resolve it, or run `mode: deploy`. You normally hit the earlier form of the same problem first, `preview mode needs a pull-request number or an explicit preview-alias`. The deploy step checks again anyway, because a preview uploaded under no alias is a version nobody can reach. ### `unsupported mode '' for target cloudflare-workers (expected deploy or preview)` `mode: rollback` is accepted by `s3-cloudfront` and `lambda-zip`, where it behaves exactly like a deploy: it publishes whatever artifact you hand it. Point `artifact-path` (or `lambda-version-label`) at the older build and it re-publishes that. What no target does is look up deployment history and pick the previous version for you. `terragrunt`, `ansible` and `cloudflare-workers` refuse the mode outright rather than pretend. ### `wrangler exited ` Wrangler's own failure, and its output is above the message in the log. The code is Wrangler's own, not `tee`'s: `pipefail` is set for exactly this, so a failed publish can't report success. The two that aren't obvious from the output are a token that authenticates but lacks a permission (mint it from the "Edit Cloudflare Workers" template), and a route or custom domain already claimed by another Worker, which fails at the bind after a successful upload. ## `target: terragrunt` ### `terragrunt-stack-env line has a glob but no KEY=VALUE after it` Every non-blank, non-comment line is `` then whitespace then `KEY=VALUE`. A glob on its own is refused rather than skipped, because a silently dropped line means a stack runs with no credential and fails at `init` with something far less specific. The companion message is `line does not assign a KEY=VALUE`, for a line whose KEY does not start with a letter or an underscore. The line itself is never printed. This input carries credentials, and the annotation it would appear in is as public as the repository, so the message names the line by its index (counting blank and comment lines, so it matches what you typed), the glob, and the KEY — never anything at or after the first `=`. A line with no whitespace on it at all, `ARM_ACCESS_KEY=…` with the glob forgotten, is reported as `ARM_ACCESS_KEY=` for the same reason. ### A stack initialises against the wrong state account Order decides it: the first matching line wins for a given key, so a `*` catch-all above a `*/prod/*` pattern captures everything. Put the specific pattern first. ### ` stack(s) failed to plan` The pull-request comment carries a redacted excerpt for each stack that changed or failed, sized so the whole comment fits GitHub's limit; the workflow run has every plan in full. Nothing applies while any stack fails to plan, approval or not. ### ` is not in terragrunt-apply-operators, so cannot force an apply` `terragrunt-apply: force` skips the approval, so it needs its own authorisation. Empty `terragrunt-apply-operators` means nobody, and the run refuses rather than applying on the strength of a flag. The normal path is an independent pull-request approval and needs no list. ### The check run says `Apply required before merge` and stays amber That's the intended state for a pull request with pending changes. It turns green once the stacks are applied, which is what makes apply-before-merge enforceable. Get an independent approval: approving applies the stacks. ### The check run says `Approved, but not applied for this commit` The pull request carries an independent approval, but this run was not started by it, so it planned and reported instead of applying. An approval applies the commit it was given for: the usual way to see this is an approval on one commit followed by a push of another, where applying the new one would apply a commit nobody reviewed. Dismiss the approval and re-approve to apply the commit in front of you. If the workflow has no `pull_request_review` trigger, add one (`types: [submitted, dismissed]`) or nothing will ever apply. `terragrunt-apply: force` applies by hand for an actor named in `terragrunt-apply-operators`. The same state appears when the run was triggered by a review that is a comment or a change request rather than an approval, and on a `workflow_dispatch` that names a pull request with `terragrunt-pull-request`: dispatching a workflow is not approving a commit, so that path plans and `terragrunt-apply: force` is its apply. ### `could not read the reviews of #` The API call failed. The run refuses to apply rather than treating an unreadable review list as "nobody objected". Retry, or check the token has `pull-requests: read`. On a push to the default branch with `terragrunt-apply-on-merge: true` this also **fails the run**, after publishing the check run and the comment: nothing blocks a merge that has already happened, so a quiet skip would leave stacks unapplied with nobody told. It fails only when there were pending changes it would have applied. A merge whose stacks all plan clean reports success, because refusing to apply nothing is not a refusal. ### The check run says `Planned; not applied` Real changes were found and none were applied, on a run with `terragrunt-apply-on-merge: true` and no open pull request: a push whose commit came from no merged pull request, one merged without an independent approval, or the scheduled drift run, which never applies. `neutral` rather than `action_required` on purpose: this check lands on a commit that is already on the branch, so there is no merge left to block, and turning the default branch red is not what fixes an unapproved merge. The stacks stay unapplied and the scheduled drift run keeps reporting them. Apply them with `terragrunt-apply: force` and an actor named in `terragrunt-apply-operators`, or fix the branch protection that let the merge through. With `terragrunt-apply-on-merge` off, which is the default, the same run reports `Apply required before merge` exactly as it always has. `neutral` is the better answer for a commit nothing is waiting on, but it is still a different answer, so it is gated on the input: a caller who opts into nothing keeps the conclusion they already have. ### `could not read the pull requests for ` Only reachable with `terragrunt-apply-on-merge: true`. The commit-to-pull-request lookup failed, so the run cannot tell which pull request authorised the merge, which means it cannot tell whether it was approved. It fails rather than guessing, but not before the check run and every step output are published, so a required check is never left never reporting on that commit. There is no plan comment on this path: the lookup is the thing that would have said which thread to comment on. "Answered, and this commit came from no merged pull request" is a different answer and is handled differently, which is the whole point of keeping the two apart. Retry, or check the token has `pull-requests: read`. Like the unreadable review list above, it fails only when there were pending changes it would have applied: a merge whose stacks all plan clean reports success and warns, because refusing to apply nothing is not a refusal. Under `terragrunt-apply: never` it only warns too, because that mode never consults an approval. ### The log says `terragrunt-apply-on-merge is off, so a push plans and applies nothing` Working as configured, and this is the default. A merge to the default branch plans the affected stacks and applies none of them, which is what this target has always done. Set `terragrunt-apply-on-merge: true` to have a merge that had an independent approval apply what it merged. ### `terragrunt-pull-request: '' is not a pull-request number` Digits only. The value becomes a path segment in a GitHub API URL, so it is checked in the action's first step, before the checkout, the tofu and terragrunt download and the assume-role. ### `could not read pull request # from ` `terragrunt-pull-request` names a pull request this run cannot see: a wrong number, or a token without `pull-requests: read`. The run ends there, before any discovery, `init` or `plan`, so nothing is half-applied and no state lock is taken. ### `the checked-out tree does not contain #'s head commit ` A warning, not a failure. Tremvok never checks out a merge ref: it plans whatever is on disk, and the `ref:` is your own `actions/checkout` step's business. This usually means `terragrunt-pull-request` was set without `ref: refs/pull//merge` and `checkout: false`, so the plan is of the default branch's code against that pull request's file list. It is a warning because `checkout: false` with a partial tree is a legitimate choice. ### ` of preflight endpoints are unreachable from this runner` `terragrunt-preflight-urls` got no answer at all from those endpoints, which is DNS, connection refused, a connect timeout, a TLS handshake failure or a proxy refusal. The line above each one carries curl's own exit code, which says which: 6 DNS, 7 refused, 28 timeout, 35 or 60 TLS. The step also prints the runner's egress IP, which is what to add if the endpoint is IP-allowlisted. This runs before the first plan on purpose: terragrunt buffers plan output to a file, so the same failure without it is a silent wait until `terragrunt-timeout`. A `401` or `403` is **not** a failure here, and an endpoint that passes has not proved your credential works. This check only asks whether anything is listening. ### `terragrunt-preflight-urls line carries credentials in the URL` A line of the form `https://user:password@host/`. These URLs reach the run log, which is public on a public repository, so the run refuses rather than probing it. The message names the line by its index and shows the URL with the userinfo replaced; it never echoes the line, for the same reason it refuses it. Put the credential where it belongs and probe the bare endpoint. An unauthenticated `401` or `403` passes this check on purpose. ### `terragrunt-preflight-urls line is not an http(s) URL` One bare URL per line, `http://` or `https://`. A bare hostname is refused because curl would guess a scheme and quietly probe something else. The line is named by index and not printed: a value in the wrong input is the value most likely to be a secret pasted somewhere it does not go. ### The log says `the saved plan for has gone stale` State moved between the plan and the apply. The run re-plans and applies the newer plan rather than refusing, and says so. `PLAN SOURCE:` in the log names which plan actually ran. If you need the reviewed plan or nothing, re-run the whole job so plan and apply are adjacent again. With `terragrunt-hold-destroys` on, or on a stack held to its `terragrunt-plan-pin`, a stack that still has changes fails instead, because the newer plan is one nobody read. Two merges close together can do this to one stack. Apply it by name with `terragrunt-stacks` and `terragrunt-apply: force` on a run from the default branch. Don't re-run the old job: it plans its own commit, which may be older than what is now merged. ### The check run says `Plan differs from its pin` A stack the change reached directly has a `terragrunt-plan-pin` file, and the saved plan's summary is not the one in it. The plan comment's `Plan pins` table shows both lines, and nothing was applied. On a pull request, either the change does something its pin does not say, or the pin is left over from an earlier change to the stack: fix whichever is wrong. After a merge, state has moved since the pull request was reviewed, so read the new plan before doing anything. To apply it anyway, name the stack with `terragrunt-stacks` and `terragrunt-apply: force`; the table still shows the difference. A plan that failed or cannot be read back, and a pin with no summary line, count as a difference. The line must be the summary as tofu prints it: `No changes.`, not the sentence that follows it. ### A scheduled run finds nothing Discovery maps changed files to stacks by path, and a change under `modules/` maps to nothing on purpose: a module has no state of its own. Guessing which stacks use it is how a small module tidy-up ends up planning the whole estate. `terragrunt-scope: all` plans everything. ### The check run says `No Terraform stacks affected` and the change was Terraform Check where the changed file sits. A file inside a stack maps to that stack; a file above the stacks maps to every stack beneath its own directory; a file under `modules/` or outside `terragrunt-root` maps to nothing. [Which stacks a change plans](setup.md#which-stacks-a-change-plans) is the whole table. Until this was fixed, only the first of those worked: a shared `root.hcl` has no enclosing stack, so it mapped to nothing and the run published `No Terraform stacks affected` as a success. The pull request merged green with every stack that includes that root unplanned. If you are pinned to a release from before the fix, that is what you are seeing, and `terragrunt-scope: all` is the workaround. ### A shared root plans more stacks than you expected Working as intended. Every stack beneath a shared `root.hcl` includes it through `find_in_parent_folders`, so changing it changes all of them, and a file directly in `terragrunt-root` reaches every stack in the estate. Move the change lower if it should not have that reach, or split the root. ## `target: ansible` ### `Vault has nothing at '' (404)` On a KV v2 mount the read path carries a `/data/` segment that the UI path does not: `secret/data/team/app`, not `secret/team/app`. That is the cause almost every time. ### `Vault refused the token for '' (403)` The token is valid and its policy doesn't grant read on that path. It needs read on the paths you reference and nothing else. ### `Vault has '' but no field '' in it. Fields present: ...` The reference is `#` and the field half doesn't exist. The message lists the field names that do, never their values. ### `cannot reach Vault at (no response)` From a private network this usually means the runner isn't on it. Check `runs-on` before checking the address. ### `ansible-ssh-private-key and ansible-ssh-private-key-vault are both set` Pick one. A literal secret and a Vault reference to the same thing is a mistake worth failing on, rather than one silently winning. ### `the playbook is not idempotent: a second check-mode run still wants to change task(s) on ` The playbook applied cleanly and then, run again in check mode, still reported changes. That means it doesn't converge. A zero exit only proves it ran. Usual causes: a `command`/`shell` task with no `creates`/`changed_when`, or a template that renders differently every run (a timestamp, an unsorted dict). Fix the task, or set `ansible-verify-idempotence: false` if you accept the gap. ### `the playbook applied cleanly but could not be re-run in check mode` A task with no check-mode support. Give it `check_mode: false`, or turn the verification off. The fix is in the playbook, not in the deploy. ### `no playbook at ` / `no galaxy requirements file at ` Paths are relative to `working-directory`. Both are checked before anything is installed. ### The playbook cannot see `VAULT_ADDR` or `VAULT_TOKEN` By design. The action removes them from the environment before `ansible-playbook` starts, so a token scoped to the fields Tremvok reads is not handed to every task, role and collection in the play. Set `ansible-vault-passthrough: true` to pass them through deliberately. With passthrough on and either `vault-addr` or `vault-token` missing, the run warns and passes neither: half a credential fails inside a task, a long way from the cause. ### The playbook cannot see `SSH_PRIVATE_KEY` or `VAULT_PASSWORD` either Also by design, and with no way to turn it off. Both are unset once their values are on disk in `0600` files, which is what `--private-key` and `--vault-password-file` point at. A play that wants the key or the vault password should take the file it is already given rather than read the environment, and unlike a Vault token there is nothing a playbook can do with these that the file does not already serve. ### `host-key checking is off for this run` A warning, not an error. You didn't supply `ansible-ssh-known-hosts`. It's a real downgrade, so it's said out loud rather than defaulted quietly. Supply the entries for anything reachable from a network you don't control. ## `target: gitops-pr` ### `gitops-pr needs yq (mikefarah/yq v4) on the runner` `yq` reads the kustomization files. GitHub's hosted runners have it; a self-hosted runner needs it installed separately. ### `gitops-pr has no rollback of its own` The full message: "revert the deploy PR's merge, which goes through review like the deploy did." `mode: rollback` is accepted and refused immediately. The correct procedure is a plain git revert of the deploy PR merge commit, opened as a pull request and merged the same way. ### `gitops-pr runs on a published release, on a push... this run is a '' event` The workflow trigger is wrong. `target: gitops-pr` runs on `release: [published]` for initial deploys, on `push` to the base branch for promotions (when a deploy PR merges), or with `gitops-tag` set for a manual dispatch. Any other event trigger hits this refusal. ### `gitops-overlays names no overlay` / `gitops-images names no image` Both inputs are required. An empty `gitops-overlays` or `gitops-images` fails the run before any API call. ### `gitops-images: '' carries a tag or digest; name the repository only` `gitops-images` lists the image repositories without a tag. The tag is what a deploy sets. Remove the `:tag` or `@sha256:...` suffix. ### `gitops-overlays: more than one overlay is called ''` The overlay name is the last path segment, and it becomes part of the deploy PR branch (`deploy//`). Two overlays that share a name produce branches that collide. Rename one of the overlay directories. ### `gitops-pr: has an images[] entry for none of: ` The kustomization in that overlay has no `images:` entry for any of the images listed in `gitops-images`. Either the overlay doesn't deploy those images (check `gitops-overlays`), or the image repository names in `gitops-images` don't match the `name` or `newName` in the kustomization. ### `gitops-pr: could not tell which pull request came from` On a push to the base branch, the run resolves the deploy PR that was merged. This fails when the GitHub API returns nothing for that commit or the token lacks `pull-requests: read`. The run stops without applying anything. ### `gitops-prereleases-until: '' is not one of gitops-overlays` The value must be the name of one of the overlays listed in `gitops-overlays`. It can't be the last overlay: a stable release whose candidate runs there needs somewhere to go next. ### `gitops-preview-urls must be a JSON object from label to URL` `gitops-preview-urls` must be valid JSON and every value must be a string. Check the quoting in the workflow. Single-line JSON works: `{"deploy/preview-1": "https://preview-1.example.com"}`. ### `gitops-preview-urls: is not one of gitops-preview-labels` Every key in `gitops-preview-urls` must match a label listed in `gitops-preview-labels`. Remove the extra key or add the label. ### `gitops-preview-labels: could not take