ci(.github/workflows): audit workflow self-references in paths (coder#25288)

nickvigilante · web-flow · commit aa87d55a6dbf · 2026-05-15T08:49:17.000-04:00
Three workflows besides `deploy-docs.yaml` ([DOCS-124](https://linear.app/codercom/issue/DOCS-124), [coder#25285](coder#25285)) self-reference in their `paths:` triggers: `docker-base.yaml`, `docs-ci.yaml`, `dogfood.yaml`. This was flagged during review of coder#25285 ([DEREM-1](coder#25285 (comment))) as a bug class worth treating uniformly. This PR is the audit. Each self-reference is either justified inline or removed: * **`docker-base.yaml`** keeps the self-reference. It's PR-only and gated by `push: ${{ github.event_name != 'pull_request' }}` on the `depot/build-push-action`, so PRs build the base image without publishing. * **`docs-ci.yaml`** drops the self-reference. The `lint` and `fmt` steps gate on `tj-actions/changed-files` matching `docs/**` or `**.md`, so a workflow-only run no-ops. `actionlint` and `make lint/actions` catch YAML problems before merge regardless. * **`dogfood.yaml`** keeps the self-reference. PR runs build images without pushing and run `terraform init` + `validate` only; pushes to main retag rolling tags on `codercom/oss-dogfood`, `oss-dogfood-vscode-coder`, and `oss-dogfood-nix`, plus `terraform apply` against dev.coder.com which produces new `coderd_template` versions with unchanged content. Idempotent and bounded. Refs DOCS-121, DOCS-129. <details> <summary>Decision table</summary> | Workflow | Self-ref location | Effect on workflow-only edit | Decision | |---|---|---|---| | `deploy-docs.yaml` | push + workflow_dispatch | Destructive (DOCS-121) | Removed in [coder#25285](coder#25285) | | `docker-base.yaml` | PR-only | Build base image, never push | Keep with inline comment | | `docs-ci.yaml` | push + PR | Empty run; lint/fmt skipped by `if:` | Remove (wasted runner minutes) | | `dogfood.yaml` | push + PR | PR: build without push, terraform validate. Main: retag rolling tags, terraform apply, new cosmetic template versions | Keep with inline comment | </details> --- _Coder Agents on behalf of @nickvigilante._
diff --git a/.github/workflows/docker-base.yaml b/.github/workflows/docker-base.yaml
@@ -9,6 +9,13 @@ on:
       - scripts/Dockerfile
 
   pull_request:
+    # Self-reference on `pull_request` is intentional: a PR that edits this
+    # workflow runs the build to verify the YAML is well-formed and the
+    # base image still builds. Pushes are gated separately by
+    # `push: ${{ github.event_name != 'pull_request' }}` on the
+    # depot/build-push-action below, so a PR builds the image but never
+    # publishes it. See DOCS-129 for the broader workflow-self-reference
+    # audit.
     paths:
       - scripts/Dockerfile.base
       - .github/workflows/docker-base.yaml
diff --git a/.github/workflows/docs-ci.yaml b/.github/workflows/docs-ci.yaml
@@ -4,16 +4,20 @@ on:
   push:
     branches:
       - main
+    # Self-reference removed from both push and pull_request: the `lint`
+    # and `fmt` steps gate on `tj-actions/changed-files` matching
+    # `docs/**` or `**.md`, so a workflow-only edit produced an empty
+    # run. `actionlint` and `make lint/actions` catch YAML problems
+    # before merge regardless. See DOCS-129.
     paths:
       - "docs/**"
       - "**.md"
-      - ".github/workflows/docs-ci.yaml"
 
   pull_request:
+    # Self-reference removed; see comment under `push:` above.
     paths:
       - "docs/**"
       - "**.md"
-      - ".github/workflows/docs-ci.yaml"
 
 permissions:
   contents: read
diff --git a/.github/workflows/dogfood.yaml b/.github/workflows/dogfood.yaml
@@ -1,6 +1,28 @@
 name: dogfood
 
 on:
+  # Self-reference on `.github/workflows/dogfood.yaml` is intentional.
+  # The runtime cost is bounded and the matrix runs validate the
+  # workflow itself end to end. See DOCS-129 for the broader
+  # workflow-self-reference audit.
+  #
+  # Effects vary by event:
+  #
+  #   PRs: `build_image` builds the image variants but never pushes
+  #   (each `depot/build-push-action` step's `push:` and the
+  #   `Push Nix image` step are gated on `github.ref ==
+  #   'refs/heads/main'`). `deploy_template` runs `terraform init` +
+  #   `validate` only; the apply step and SHA/title gathering are
+  #   gated on main.
+  #
+  #   Pushes to main: `build_image` retags rolling tags on
+  #   `codercom/oss-dogfood` (`:latest`, `:22.04`, `:26.04`),
+  #   `codercom/oss-dogfood-vscode-coder` (`:latest`), and
+  #   `codercom/oss-dogfood-nix` (`:latest`), plus a per-branch tag on
+  #   each. `deploy_template` runs `terraform apply` and creates new
+  #   `coderd_template` versions on dev.coder.com whose `name` is the
+  #   commit short SHA. Content is unchanged when neither `dogfood/**`
+  #   nor the flake files changed, so the new versions are cosmetic.
   push:
     branches:
       - main
