Skip to content

docs(safety): add header noting reusable consumers#73

Merged
j7an merged 1 commit into
mainfrom
docs/dep-safety-header
May 28, 2026
Merged

docs(safety): add header noting reusable consumers#73
j7an merged 1 commit into
mainfrom
docs/dep-safety-header

Conversation

@j7an
Copy link
Copy Markdown
Owner

@j7an j7an commented May 28, 2026

Summary

  • Add a 4-line top-of-file comment to dependency-safety.yml documenting that the workflow is reusable, consumed both externally (uses: j7an/shared-workflows/.github/workflows/dependency-safety.yml@v3) and internally (by ci-safety.yml, registered as "CI Safety").
  • File-level no-op behaviorally — comment only.

Why (genuinely useful)

When landing in this file from search or a stack trace, the first signal a reader gets is the name: line and the on: workflow_call: block. Neither tells them this workflow is dogfooded by ci-safety.yml in the same repo, or why ci-safety.yml's display name differs from this one. Four lines of comment makes the partnership self-documenting and avoids the next maintainer relearning the relationship by archaeology.

Why (the registration-refresh side effect)

This commit also has a side effect: GitHub re-registers the workflow on this file change, refreshing its display name from the stale path-fallback (".github/workflows/dependency-safety.yml") to its declared name: ("Dependency Safety"). That stale value was the residue of the original name collision with ci-safety.yml (resolved in #72), and was causing GitHub's scheduler to emit phantom startup-failure runs (0 jobs, no logs) on every push that modifies this file:

Disable/enable via the workflows API was attempted as a no-commit alternative — it changed state to disabled_manually and back to active, but did not refresh the registered name. Only a push that modifies the workflow file triggers the resolver to re-read the name: field.

Test plan

  • CI: ci-scripts.yml is green on this PR.
  • CI: CI Safety workflow runs the non-bot early-exit path on this PR and passes.
  • After merge: confirm the workflow registry shows name: "Dependency Safety" (not the path-fallback):
    gh api repos/j7an/shared-workflows/actions/workflows/281959865 --jq '{id, name, state, updated_at}'
  • After merge: confirm no new phantom failure run appears on the merge commit for .github/workflows/dependency-safety.yml. If one still appears, the registry refresh didn't take and we need a different approach.
  • Deferred to next Dependabot PR: confirm the reusable workflow still runs end-to-end and the dependency-safety / gate row remains clickable (validates the fix(safety): make dependency-safety/gate status clickable #71 fix is unaffected).

Document that this workflow is consumed both externally (via the
public uses: reference) and internally by ci-safety.yml — and that
ci-safety.yml is intentionally registered as "CI Safety" to keep
this workflow's display name "Dependency Safety" unambiguous in
the Actions UI.

Side effect: this commit causes GitHub to re-register the workflow,
refreshing its display name from the stale path-fallback value
(".github/workflows/dependency-safety.yml") to "Dependency Safety".
That stale value is the residue of the original name collision with
ci-safety.yml (resolved in #72) and was causing GitHub's scheduler
to emit phantom startup-failure runs on every push that modifies
this file. Disable/enable via the API did not refresh the
registration; only a file-level change does.

Refs runs:
- https://github.com/j7an/shared-workflows/actions/runs/26556546736
- https://github.com/j7an/shared-workflows/actions/runs/26556959117
@j7an j7an merged commit 8f0bb35 into main May 28, 2026
5 checks passed
@j7an j7an deleted the docs/dep-safety-header branch May 28, 2026 05:49
j7an added a commit that referenced this pull request May 28, 2026
Diagnostic PR. Previous attempts to refresh dependency-safety.yml's
registered display name failed:
- #72 (rename ci-safety to break collision): didn't refresh this
  workflow's record (only ci-safety's record refreshed).
- API disable/enable: state cycled but name stayed at the path fallback.
- #73 (touch the file via comment header): updated_at advanced but
  name field still stuck at ".github/workflows/dependency-safety.yml".

Hypothesis: GitHub re-resolves the name field only when the value of
the YAML `name:` key itself changes — not on file-content changes or
API-level state cycles.

This PR changes the name from "Dependency Safety" to "Dependency
Safety (reusable)" to force resolution. Post-merge verification:
  gh api repos/.../actions/workflows/281959865 --jq '.name'

If that returns "Dependency Safety (reusable)", the resolver did run
and we can decide whether to rename back. If it stays at the path
string, this is a GitHub-side bug and we escalate via support ticket.

The display name is cosmetic: it appears in consumers' Actions UIs
as the row label, but does not affect the `uses:` path. Consumer repos
will see the label "Dependency Safety (reusable)" until/unless we
rename back.

Refs: phantom runs blocking ci-safety dogfood since 2026-05-28.
j7an added a commit that referenced this pull request May 28, 2026
…ger (#76)

Background: ci-safety.yml's dogfood (`safety / scan` job) has been
silently broken since 2026-05-28 05:21 — every PR produces a 0-job
phantom startup_failure. The complete file-level diff between the
last working state (HEAD a8655fe at 2026-05-26 06:19) and the first
broken state (HEAD 01d9280 at 2026-05-28 05:21) is exactly these 9
lines: three `-f target_url=...` arguments added to three
`gh api .../statuses/${HEAD_SHA}` calls inside dep-safety.yml's
run-blocks.

This PR reverts those 3 lines (plus the 3 backslash-continuation
modifications they required on the preceding `-f description=` lines)
to test whether they are causally involved in the phantom-failure
behavior.

Possible outcomes when this lands on a PR:
1. Phantom failures STOP and ci-safety's `safety / scan` job runs
   again → the target_url expressions are causally involved. We then
   need to either find another way to make the gate clickable or
   accept the unclickable status.
2. Phantoms persist → the target_url changes are NOT involved; the
   regression must be a coincident GitHub-side platform change.
   Support ticket is the only path remaining.

Refs phantom runs:
- 26556360487 (first phantom, our feature branch push 2026-05-28 05:21)
- 26556546736 (PR #71 merge)
- 26556922328 (PR #72 feature branch)
- 26557123379 (PR #73 feature branch)
- 26557436258 (PR #74 merge)
- 26558104480 (PR #75 merge — new workflow_id 284671829, still broken)

The diagnostic itself reverts to the working file-content state for
just this file; everything else (file rename to dep-safety.yml, doc
header from #73, name="Dependency Safety (reusable)" from #74) is
left intact since we want to test the target_url-specific hypothesis
in isolation.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant