Skip to content

ci(.github/workflows): deploy docs previews from a workflow pinned to main - #32334

Draft
sreya wants to merge 1 commit into
mainfrom
sreya/docs-preview-trusted-workflows
Draft

sreya wants to merge 1 commit into
mainfrom
sreya/docs-preview-trusted-workflows

Conversation

@sreya

@sreya sreya commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator

Summary

Docs PR previews (#30698) have failed on every run since the DOCS_ENGINE_APP_* and VERCEL_PREVIEW_TOKEN secrets were removed; the last green run was 2026-11-14. This changes where the privileged jobs are defined and where their credentials come from, so previews can be turned back on without handing those credentials to every pull request.

Previews stay off until the Google Cloud side exists (see Rollout). Until then both workflows are skipped, so merging this also removes the failing check from every docs PR.

Problem

docs-pr-preview-deploy.yaml runs on pull_request, which reads workflow files from the pull request. Its job split keeps PR content away from the secrets, but anyone who can push a branch can edit the workflow itself and read them. The docs-preview environment has no branch policy or required reviewers, so an environment secret is no better protected. Moving the App key into KMS does not help on its own if the identity allowed to use the key trusts that environment.

Fix

Privileged jobs are read from main. engine, build and deploy move to a new reusable workflow, docs-pr-preview-publish.yaml. docs-pr-preview-deploy.yaml keeps the trigger and the comment job and calls it as coder/coder/.github/workflows/docs-pr-preview-publish.yaml@main. A job in a called workflow presents a job_workflow_ref claim naming that file and ref, so a workload identity can trust the file on main and nothing a pull request can edit.

No GitHub secrets. The docs-engine App key stays in Cloud KMS: the engine job has KMS sign the App JWT, then exchanges it for a token limited to contents: read on coder/docs-engine. The Vercel token is read from Secret Manager inside the one step that uses it.

The caller is treated as hostile. It passes no inputs; the PR number and commit come from the event. The jobs refuse anything but an open pull_request from a branch in this repository. The static export now travels as an archive checked against a digest in a job output, as the engine source already was, because another job in the caller's run can replace an artifact. The build job gets no id-token permission, since any job in that file that can request an OIDC token can sign in.

Engine pin floor. docs/.engine-ref must still name a commit on docs-engine main, and may no longer name one older than the default branch's pin; an older pin builds with the default branch's. The deploy job runs that engine's layout script beside the Vercel token, so an old engine should not be selectable.

--target=preview on the deploy, so a preview cannot become the project's production deployment. This is the fix from #32126, which this conflicts with.

Cleanup reads the Vercel token the same way. A refused deployment listing now fails the run: the weekly groom read it as an empty project and reported success while every preview stayed up. The groom now runs daily, and closes of pull requests into a non-default branch are left to it, because pull_request_target runs the base branch's copy of the file, which the identity refuses.

Rollout

Nothing here runs until the following exist. None of it can be done from this repository.

  1. A workload identity provider that accepts a GitHub token only when repository_id == 440752086 and job_workflow_ref is coder/coder/.github/workflows/docs-pr-preview-publish.yaml@refs/heads/main or coder/coder/.github/workflows/docs-pr-preview-cleanup.yaml@refs/heads/main. The repository condition is required: any repository can call a public reusable workflow, and job_workflow_ref would still name this file.
  2. A new private key for the coder-docs-engine-reader App, imported into Cloud KMS as RSA_SIGN_PKCS1_2048_SHA256, and a service account that may only sign with it. The old key was a repository secret, so it should be deleted, not imported.
  3. A new Vercel token limited to the preview project, in Secret Manager, and a service account that may only read it.
  4. Repository variables DOCS_PREVIEW_WORKLOAD_IDENTITY_PROVIDER, DOCS_PREVIEW_ENGINE_SERVICE_ACCOUNT, DOCS_PREVIEW_DEPLOY_SERVICE_ACCOUNT, DOCS_ENGINE_APP_CLIENT_ID, DOCS_ENGINE_APP_KMS_KEY_VERSION and DOCS_PREVIEW_VERCEL_TOKEN_SECRET. The header of docs-pr-preview-publish.yaml gives their formats. Setting the first one turns previews on.
  5. After the first green run, dispatch docs-pr-preview-cleanup to delete the previews of pull requests closed since 2026-11-15, which are still being served (for example pr-31990), and delete the untagged production deployment that ci: deploy docs previews to the preview target only #32126 describes.

Verification

These workflows cannot run end to end until they are on main and the identity exists, so no real run has exercised them. What was run:

  • Every new or changed run: block except the token revocation, extracted from the YAML and executed against stand-ins for Cloud KMS, GitHub, Secret Manager and Vercel. The KMS path used a real RSA key: the resulting JWT verifies with openssl dgst -sha256 -verify, and a refused signature, an unset variable or the wrong key each exit without writing a token.
  • Pin selection against a scratch git history: a newer or equal pin builds as pinned, an older one builds the default branch's, and a commit off main or a missing commit is refused.
  • The export check against archives holding a symbolic link, a hard link and a FIFO, each refused before anything is unpacked.
  • test-docs-pr-preview-cleanup.sh (new) runs the cleanup script straight out of the workflow. Its listing case fails against the previous listing code with exit status 0, want nonzero.
  • test-docs-preview-mapper.sh: its three assertions on the workflow layout now read the new files, and two were added (the build job holds no identity; no preview workflow reads a GitHub secret). Each of the five fails when the workflow is changed to break it.
  • actionlint, zizmor, ShellCheck and shfmt report nothing.

Not addressed

  • The docs-engine-source artifact holds the private engine's source, and anyone with read access to this public repository can download it for a day after each build. That predates this change.
  • npx vercel@65.11.0 still resolves its dependency tree at run time in the job that holds the Vercel token.

Note

An AI agent (Xum) wrote this change for @sreya and ran the checks above.

… main

Docs PR previews have failed since their GitHub secrets were removed.
Putting the secrets back would not be safe: docs-pr-preview-deploy.yaml
runs on pull_request, which reads workflow files from the pull request,
so anyone who can push a branch could rewrite the jobs that hold them.

Move the engine, build and deploy jobs into docs-pr-preview-publish.yaml
and call it as coder/coder/...@main. A job in a called workflow presents
a job_workflow_ref claim naming that file and ref, so a Google Cloud
workload identity can trust the file on main and nothing a pull request
can edit. The jobs read no GitHub secret:

- The docs-engine App key stays in Cloud KMS. The engine job has KMS
  sign the App JWT and exchanges it for a read token on docs-engine.
- The Vercel token is read from Secret Manager in the step that uses
  it.

The caller is untrusted. It passes no inputs, the jobs refuse anything
but an open pull request from a branch in this repository, and the
static export is now checked against a digest in a job output, as the
engine source already was, because another job in the run can replace
an artifact. docs/.engine-ref may not name an engine older than the
default branch's pin. The deploy passes --target=preview.

Cleanup gets the Vercel token the same way. A refused deployment
listing now fails the run; the groom used to read it as an empty
project and report success. The groom runs daily, and closes of pull
requests into a non-default branch are left to it.

Both workflows are skipped while DOCS_PREVIEW_WORKLOAD_IDENTITY_PROVIDER
is unset, so previews stay off, without a failing check, until the
identity exists.
@sreya
sreya temporarily deployed to main November 17, 2026 20:33 — with GitHub Actions Inactive
@sreya
sreya temporarily deployed to main November 17, 2026 20:33 — with GitHub Actions Inactive

This branch was previously deployed

1 inactive deployment
main — 92409434 Deployed Nov 17, 2026 by sreya via community-label #258942
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant