Skip to content

Setting Tremvok up

Pick a target, add the job, grant the permissions that target needs. The action reference 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:

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 <page>/index.md (the llmstxt.org convention), announced with <link rel="alternate" type="text/markdown">, 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:

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 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:

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 <host> <username>:<token> per line:

      - 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.<credentialled>.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://<host>/<repo>/, and one hostname serves every repository by path:

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://<host>/<repo>/. MkDocs emits <link rel="canonical"> 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-<repo>. It declares [assets] and, deliberately, no route and no workers_dev URL.
  3. A [[services]] block in the router's config, binding <REPO> to docs-<repo>. 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 <host> 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 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 <host>/<repo>:

          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/<repo>.json, which is the corpus the documentation MCP servers read:

          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/<repo>.json beside the index:

{
  "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, 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

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-<number>

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.

          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

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:<owner>/<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/<name>; 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?

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 <operation-id>.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 <operation-id>.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.

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.

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:

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/. Both need id-token: write for the role, and pull-requests: write for the sticky preview comment.

terragrunt

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 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 <ID>. 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:

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:

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@<pinned sha>  # 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:

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:

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.

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@<pinned sha>  # 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/<n>/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:

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:

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:<owner>/<repo>:pull_request for the plan on a pull request, and repo:<owner>/<repo>:ref:refs/heads/<default-branch> 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.<your- subdomain>.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:

- 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

- 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:

## 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:

with:
  target: terragrunt
  terragrunt-stack-env: |
    */prd/*|*/prod/*  ARM_ACCESS_KEY=${{ secrets.PRD_STATE_KEY }}
    *                 ARM_ACCESS_KEY=${{ secrets.STATE_KEY }}

One <glob> 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

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:

{
  "Effect": "Allow",
  "Principal": { "Federated": "arn:aws:iam::<account>: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.

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.

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 <path>#<field>. 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.

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; 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:

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 <gitops-branch-prefix>/<environment> 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.

- 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.