Automations

Every automation in this repository, grouped by what triggers it. Use this to find out what already runs before adding something new, and to know what to update when you change or rename a job.

When you add or rename an automation, update this file and the workflows: list in notify-automation-failures.yml. That list matches on a workflow's name: value, so a rename silently unhooks its failure alert.

Content generation

Automations that write content into the repository. Each one opens a pull request rather than committing to main.

Automation	Trigger	Writes	Source	Notes
Snipsync	Daily at 06:00 UTC, or on demand	Code snippets throughout docs/	snipsync.yml, snipsync.config.yaml	Reuses one branch, snipsync/daily-update, and updates the open pull request instead of stacking new ones. Edit the source repository named in the <!--SNIPSTART--> wrapper, not the page.
CLI command reference	A published release in temporalio/cli	docs/cli/command-reference/	update-cli-docs.yml, bin/post-process-cli-docs.js	Generated twice, once for temporalio/cli and once for temporalio/cloud-cli into a cloud/ subdirectory, because the two share option set names and collide in a single invocation. The post-processor recreates the index.mdx landing pages and sidebar entries from the generated command pages.
Custom role permissions	Mondays at 09:00 UTC, or on demand	docs/cloud/manage-access/_custom_role_permissions_table.mdx	update-custom-role-permissions.yml, bin/generate-custom-role-permissions-table.js	Reads custom_role_permissions.json from the private temporalio/saas-proto.
SDK version chips	Daily at 09:00 UTC, or on demand	src/data/sdk-versions.json	update-sdk-versions.yml, bin/update-sdk-versions.js	Sourced from each SDK's package registry.
AI cookbook sync	Every build, and on yarn start	ai-cookbook/	bin/sync-ai-cookbook.js, bin/ensure-ai-cookbook.js, bin/write-ai-cookbook-index.js	Runs from the prebuild script, so it is part of the Vercel build rather than a workflow. Clones temporalio/ai-cookbook on every build, which wipes and re-writes every top-level .mdx in ai-cookbook/. write-ai-cookbook-index.js writes the landing page (ai-cookbook/index.mdx, tracked at bin/ai-cookbook-index-template.mdx) back in afterward, since that page isn't recipe content and can't be committed inside the gitignored sync output directly.

All four workflows authenticate as the temporal-cicd GitHub App. A token from that app reaches only this repository unless the step sets owner and repositories, and GitHub answers a request for an unreachable private repository with a 404 rather than a 403, so a scope mistake looks like a missing file.

Pull request checks

Check	Runs on	Fails on findings	Source	Notes
Docs Build Check	Changes to docs, src/, static/, or build config	Yes	build-check.yml, bin/parse-build-failure.js	Runs the same production build Vercel runs. Vercel reports only that a branch failed to deploy, so this job parses the build log and comments the specific page or link that needs fixing.
Check Redirects	Every pull request	Yes	check-redirects.yml, bin/check-redirects-for-moved-pages.js	Fails when a page moves or is deleted without a matching redirect in vercel.json.
Check Metrics Reference	Changes to docs/references/sdk-metrics.mdx	Yes	check-metrics-reference.yml, bin/check-metrics-reference.js	Checks the page against itself. The comparison with the SDK sources is a separate, advisory job.
Environment config drift	Changes to the client environment configuration page	Yes	env-config-drift.yml, bin/check-env-config-table.js	Also runs weekly, because it fetches sources over the network and an outage should not block unrelated pull requests.
Mermaid CI	Changes under docs/	Yes	mermaid-ci.yml, scripts/lint-mermaid.mjs	Validates diagram syntax across the docs tree.
Vale CI	Changes under docs/	No	vale-ci.yml, .vale-ci.ini	Runs only the rules in .vale-ci.ini, with fail_on_error: false and results limited to changed context. Treat those rules as the bar, not the full style set. See AGENTS.md.
Check Orphan Pages	Changes to docs or sidebars.js	No	check-orphan-pages.yml, bin/check-orphan-pages.js	Never fails; comments and annotates only. Accepted exceptions belong in bin/orphan-pages-baseline.json with a note. See UTILITIES.md.
Check Metrics Against SDKs	Changes to the metrics page or its checker	No	check-metrics-against-sdks.yml	Drift reports but does not fail. On its scheduled runs it manages a tracking issue instead.
Docs Preview Links	Every pull request	No	docs-preview-links.yml, bin/generate-docs-preview-list.js	Reads the preview URL out of Vercel's own comment, then upserts a single comment listing the pages the pull request changes.
Visual Comparison	Pull requests labeled visual-comparison	No	visual-comparison.yml	Compares against baselines captured weekly by Screenshot Capture, and publishes its HTML report to a throwaway Vercel deployment linked from a pull request comment. Takes about 15 minutes. See UTILITIES.md.
Dependabot	Weekly, for npm and GitHub Actions	No	.github/dependabot.yml	14-day cooldown on new versions.

"Fails on findings" means the job turns red, not that merging is prevented. Branch protection on main requires only the Vercel check, so every job in this table can be merged past.

Scheduled and event-driven

Automation	Trigger	What it does
Snipsync	Daily, 06:00 UTC	Syncs code snippets. See Content generation.
Update SDK Versions	Daily, 09:00 UTC	Refreshes the version chips shown on /develop.
Update Custom Role Permissions	Mondays, 09:00 UTC	Regenerates the Cloud permissions table.
Check Metrics Against SDKs	Mondays, 10:00 UTC	Compares the metrics reference with the SDK default branches. Advisory by design: the SDK default branches run ahead of released versions, so instead of failing it opens a tracking issue, updates that issue while the drift lasts, and closes it once the page and the sources agree. Record a deliberately undocumented metric in bin/metrics-baseline.json.
Environment config drift	Mondays, 15:00 UTC	Compares the environment variable table with five SDK and CLI repositories.
Screenshot Capture	Sundays, 00:00 UTC	Captures Playwright baselines for Visual Comparison, sharded four ways, retained 14 days.
Warm Build Cache	Every push to main	Rebuilds so dependency and build caches stay warm, so a new pull request's first Docs Build Check isn't a cold install. GitHub falls back from the current ref to the base branch to the default branch when restoring a cache, so pull request runs restore what merges to main saved. Docs Build Check restores these caches but never saves them, because the OG image and rspack caches are large and keyed per run.
Delete Visual Tests Reports	Branch deletion	Removes that branch's reports from gh-pages.
Notify Automation Failures	Another workflow completes	Posts failures to Slack. See Failure alerting.

Failure alerting

notify-automation-failures.yml posts to Slack when a workflow that has nowhere else to report fails. Pull request checks are deliberately excluded, since they already surface on the pull request.

Two things to know:

• The workflows: list matches each workflow's name: value, not its filename. Renaming a workflow silently stops matching it.
• Dependabot runs as a GitHub-managed workflow and cannot be listed, so its failures are not alerted.

Build time

These run on every Vercel build rather than in GitHub Actions.

Automation	What it does
plugins/markdown-pages	Emits a clean .md for every page, plus llms.txt and llms-full.txt. See MARKDOWN_PIPELINE.md.
plugins/og-image	Renders per-page Open Graph cards, cached by content hash
plugins/cookbook-index	Supplies the recipe list/metadata CookbookHome and CookbookDocItem render — the landing page itself is a normal doc (ai-cookbook/index.mdx, written by bin/write-ai-cookbook-index.js) covered by plugins/markdown-pages/plugins/og-image like any other page
plugins/cloud-region-counts	Counts regions from the region reference pages
middleware.js	Serves the .md version of a page for Accept: text/markdown
prebuild / postbuild	Syncs the AI cookbook, then verifies the preloaded font hash matches vercel.json

Local

.husky/pre-commit is a shim that sources an untracked .husky/pre-commit.local if you create one. Nothing runs by default.