coder · nickvigilante · May 15, 2026 · May 13, 2026 · May 13, 2026 · May 14, 2026
@@ -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

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

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