Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

chore(ci): trial workflow lockfiles (#125109)

Raúl Negrón-Oterob09683d6342b
diff --git a/.agents/skills/authoring-ci-workflows/SKILL.md b/.agents/skills/authoring-ci-workflows/SKILL.md
index fb611f4fa6ab..0aa6b309107a 100644
--- a/.agents/skills/authoring-ci-workflows/SKILL.md
+++ b/.agents/skills/authoring-ci-workflows/SKILL.md
@@ -1,7 +1,7 @@
---
name: authoring-ci-workflows
description: >
- Use when adding or editing a GitHub Actions workflow, composite action, or reusable workflow under `.github/` — new CI jobs, triggers, matrices, checkout/clone tuning, action pinning, GitHub App token auth, concurrency groups, `timeout-minutes`, `paths` filters, caching, or runner choice.
+ Use when adding or editing a GitHub Actions workflow, composite action, reusable workflow, or `actions.lock` under `.github/`: new CI jobs, triggers, matrices, checkout/clone tuning, action pinning and lockfiles, GitHub App token auth, concurrency groups, `timeout-minutes`, `paths` filters, caching, or runner choice.
Covers PostHog's workflow-authoring conventions and the reasons behind them: the 500-runs/10s dispatch cap, shallow vs full clone, per-SHA push concurrency, dedicated App-token rate-limit buckets, and fork-safe secrets on a public repo.
Points to the linters (`bin/hogli lint:workflows`, actionlint) that enforce the mechanical rules, and to the narrower skills for production deploys, secrets, and Depot runners.
Not for debugging red CI (use debugging-ci-failures) or wiring a new secret end to end (use managing-github-actions-secrets).
@@ -30,7 +30,7 @@ The linters own the mechanical rules (below); this skill is the **judgment calls
Run `bin/hogli lint:workflows` and `actionlint` before pushing — they gate CI, and they (not this list) are the source of truth for what's enforced.
Today that's: `timeout-minutes` on every job, the canonical PR concurrency block, a repo-wide budget for unscoped PR event dispatches, `dorny/paths-filter` negation safety, justification for full-depth checkouts, cache-write gating, semgrep service coverage, MCP path-filter coverage of the trees the MCP build compiles, Storybook path-filter coverage of every `staticDirs` source, required-check gate hygiene, secrets a reusable workflow reads being declared and passed by its callers, runner labels that name an OS version rather than a floating `-latest` alias, `#`-free values for the action inputs an inner shell re-parses, and generic GHA correctness (bad `secrets.*` / `needs:` refs, deprecated `::set-output`, unknown runner labels).
-Third-party action digests are bumped by Renovate.
+Renovate bumps third-party action digests, except in workflows listed in `actions.lock`.
## Check what a condition does before you push it
@@ -293,9 +293,11 @@ Measured checkout-step durations, from the GitHub API on real runs:
## Pinning and tool versions
-- **Pin every third-party action to a full 40-char commit SHA** with a `# vX.Y.Z` comment.
- A moved tag can ship malicious code; pinning is also reproducible and skips a per-run GitHub-API version lookup.
- The only sanctioned exception is a debug-only action.
+- **Pin third-party actions to full 40-character commit SHAs** with `# vX.Y.Z` comments.
+ Workflows already listed in `.github/workflows/actions.lock` may use exact version tags backed by locked commits.
+ Before editing one or the lockfile, read [Maintaining workflow lockfiles](references/workflow-lockfiles.md).
+ Keep inline SHA pins elsewhere: copying an onboarded workflow does not onboard its copy.
+ The other sanctioned exception is a debug-only action.
In-repo composites use a local path with no ref (`uses: ./.github/actions/pnpm-install`).
- **Node version comes from `.nvmrc`** — `node-version-file: .nvmrc`, never a hardcoded `node-version:`.
Sparse-checkout `.nvmrc` if the job has no checkout.
@@ -545,7 +547,8 @@ Before that date, fix or add to the baseline every violation that landed during
- [ ] Canonical `concurrency:` block (per-SHA push arm if it publishes on push).
- [ ] `timeout-minutes` on every job (except reusable-caller jobs).
- [ ] Checkout names only the paths the job reads (`sparse-checkout` + cone mode off), or is shallow; bounded `1000 + blob:none` only for base diffing.
-- [ ] Third-party actions SHA-pinned; Node from `.nvmrc`; `setup-uv` version pinned; runner labels name an OS version (`ubuntu-24.04`, never `ubuntu-latest`).
+- [ ] Third-party actions SHA-pinned, or the already-onboarded workflow's lockfile regenerated and verified.
+- [ ] Node from `.nvmrc`; `setup-uv` version pinned; runner labels name an OS version (`ubuntu-24.04`, never `ubuntu-latest`).
- [ ] External fetches retry (`--retry-all-errors`), except where a repeat has a side effect.
- [ ] High-volume API calls on a dedicated App token with `|| github.token` fork fallback.
- [ ] Fork PRs handled: secret-needing steps guarded with the same-repo `if:`; no secret-injecting build runs on forks.
diff --git a/.agents/skills/authoring-ci-workflows/references/workflow-lockfiles.md b/.agents/skills/authoring-ci-workflows/references/workflow-lockfiles.md
new file mode 100644
index 000000000000..82b4141f2479
--- /dev/null
+++ b/.agents/skills/authoring-ci-workflows/references/workflow-lockfiles.md
@@ -0,0 +1,39 @@
+# Maintaining workflow lockfiles
+
+Read this before changing a workflow listed in `.github/workflows/actions.lock`, its action dependencies, or the lockfile itself.
+
+The lockfile's `workflows` section lists the onboarded workflows.
+Onboard another workflow in its own change, and add it to the Renovate exclusion in `.github/renovate.json5` in that change.
+
+## Update and verify
+
+Use the `gh-actions-lock` version pinned in `.github/workflows/ci-lint-workflows.yml`.
+
+After changing an onboarded workflow's action references, regenerate and verify only that workflow.
+Without a workflow path, `gh actions-lock` onboards every workflow.
+
+```sh
+gh actions-lock .github/workflows/<workflow>.yml
+gh actions-lock --verify .github/workflows/<workflow>.yml
+```
+
+Commit the workflow and the generated lockfile together.
+
+Keep the rule-specific `nosemgrep` annotation on each locked tag reference.
+Semgrep's mutable-action-tag rule does not read `actions.lock`.
+
+Review the generated diff:
+
+- Confirm that changed commits match the intended dependency update, and investigate changed repository or owner IDs.
+- Confirm that the run onboarded no other workflow and rewrote no shared action.
+
+Never delete the lockfile to resolve an error.
+Restore a valid copy and regenerate.
+Do not use `--relock` or `--accept-moved` to silence a provenance error before you review the upstream change.
+
+## Coverage boundaries
+
+- The lockfile does not cover remote reusable-workflow calls at `jobs.<job_id>.uses`. Keep their inline SHA pins.
+- `gh-actions-lock` does not follow local `./` actions. A migration to `$/` changes which commit supplies the action, so keep it out of routine lockfile maintenance.
+
+See GitHub's [lockfile maintenance guide](https://docs.github.com/en/actions/how-tos/secure-your-work/lock-workflow-dependencies) and the [gh-actions-lock limitations](https://github.com/github/gh-actions-lock#limitations).
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 2bcc35108e7d..9337c5f561a0 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -93,6 +93,9 @@ products/isolation_baseline.txt @PostHog/team-devex
.github/pull_request_template.md @PostHog/team-devex
.agents/skills/writing-pr-descriptions/ @PostHog/team-devex
+# A changed commit in the lockfile means a workflow now runs different third-party code.
+.github/workflows/actions.lock @PostHog/team-devex
+
# The mobile owner reviews app changes and the workflows that build and release it.
products/mobile/** @cvolzer3
products/desktop/apps/mobile/** @cvolzer3
diff --git a/.github/renovate.json5 b/.github/renovate.json5
index 662be1a98b73..35eba720665d 100644
--- a/.github/renovate.json5
+++ b/.github/renovate.json5
@@ -176,6 +176,13 @@
matchManagers: ['github-actions'],
groupName: 'github-actions',
},
+ // Renovate cannot regenerate `.github/workflows/actions.lock`, so a bump in a locked workflow fails Lint workflows.
+ // List each workflow from that file's `workflows` section here
+ {
+ matchManagers: ['github-actions'],
+ matchFileNames: ['.github/workflows/ci-paths-filter.yml'],
+ enabled: false,
+ },
// The sandbox images and the Modal slim image rebuild only when this pin changes,
// so skip the dashboard approval and open the PR as soon as nodesource ships a release
{
diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock
new file mode 100644
index 000000000000..e68ac1ee27bb
--- /dev/null
+++ b/.github/workflows/actions.lock
@@ -0,0 +1,19 @@
+# This file is machine-generated by `gh actions-lock`.
+# Do not edit by hand; run `gh actions-lock` to update.
+# Docs: https://gh.io/actions-lockfile
+version: 'v0.0.3'
+workflows:
+ '.github/workflows/ci-paths-filter.yml':
+ - 'actions/[email protected]'
+ - 'actions/[email protected]'
+dependencies:
+ 'actions/[email protected]':
+ ref: 'v6.0.2'
+ commit: 'sha1-de0fac2e4500dabe0009e67214ff5f5447ce83dd'
+ owner_id: 44036562
+ repo_id: 197814629
+ 'actions/[email protected]':
+ ref: 'v6.2.0'
+ commit: 'sha1-6044e13b5dc448c55e2357c09f80417699197238'
+ owner_id: 44036562
+ repo_id: 189476904
diff --git a/.github/workflows/ci-lint-workflows.yml b/.github/workflows/ci-lint-workflows.yml
index fba8d76a5df9..6887be4c8155 100644
--- a/.github/workflows/ci-lint-workflows.yml
+++ b/.github/workflows/ci-lint-workflows.yml
@@ -41,6 +41,16 @@ jobs:
- name: Lint workflows
run: ./bin/hogli lint:workflows
+ - name: Verify Actions lockfile
+ if: ${{ !cancelled() }}
+ env:
+ GH_TOKEN: ${{ github.token }}
+ run: |
+ gh extension install github/gh-actions-lock --pin v0.4.0
+ # Only onboarded workflows are verified, because an unscoped run fails on every workflow not yet in the lockfile.
+ mapfile -t workflows < <(yq '.workflows | keys | .[]' .github/workflows/actions.lock)
+ gh actions-lock --verify "${workflows[@]}"
+
workflow-run-plans:
name: Workflow run plans
runs-on: ubuntu-24.04
diff --git a/.github/workflows/ci-paths-filter.yml b/.github/workflows/ci-paths-filter.yml
index 4262c7415c7d..3f4e68cc9e37 100644
--- a/.github/workflows/ci-paths-filter.yml
+++ b/.github/workflows/ci-paths-filter.yml
@@ -28,8 +28,10 @@ jobs:
run:
working-directory: .github/actions/${{ matrix.action }}
steps:
- - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+ # nosemgrep: yaml.github-actions.security.github-actions-mutable-action-tag.github-actions-mutable-action-tag
+ - uses: actions/[email protected]
+ # nosemgrep: yaml.github-actions.security.github-actions-mutable-action-tag.github-actions-mutable-action-tag
+ - uses: actions/[email protected]
with:
node-version-file: .nvmrc
token: ${{ github.token }}