From aa87d55a6dbfacaed9b3f8d9645e17f0eeac8983 Mon Sep 17 00:00:00 2001
From: Nick Vigilante <nickvigilante@users.noreply.github.com>
Date: Fri, 15 May 2026 08:49:17 -0400
Subject: [PATCH] ci(.github/workflows): audit workflow self-references in
 paths (#25288)

Three workflows besides `deploy-docs.yaml`
([DOCS-124](https://linear.app/codercom/issue/DOCS-124),
[#25285](https://github.com/coder/coder/pull/25285)) self-reference in
their `paths:` triggers: `docker-base.yaml`, `docs-ci.yaml`,
`dogfood.yaml`. This was flagged during review of #25285
([DEREM-1](https://github.com/coder/coder/pull/25285#discussion_r3234975475))
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 [#25285](https://github.com/coder/coder/pull/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._
---
 .github/workflows/docker-base.yaml |  7 +++++++
 .github/workflows/docs-ci.yaml     |  8 ++++++--
 .github/workflows/dogfood.yaml     | 22 ++++++++++++++++++++++
 3 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/docker-base.yaml b/.github/workflows/docker-base.yaml
index 21b33c55c1..4bc86c107e 100644
--- 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
index 7d07749345..83d8cc674d 100644
--- 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
index ce629a4ed1..b039ccc37f 100644
--- 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