Skip to content

docs(workflows): document all reusable workflows and drop phantom entry - #70

Merged
sbaerlocher merged 2 commits into
mainfrom
fix/workflows-readme
Aug 7, 2026
Merged

docs(workflows): document all reusable workflows and drop phantom entry#70
sbaerlocher merged 2 commits into
mainfrom
fix/workflows-readme

Conversation

@sbaerlocher

Copy link
Copy Markdown
Member

Summary

  • Remove the ci-go-action.yml section: the file does not exist, so copying its usage block produces a workflow resolution error. Its content described jobs now split across ci-lint.yml and ci-go.yml.
  • Document the six previously missing reusables: ci-go.yml, ci-lint.yml, release-go.yml, security-code.yml, security-config.yml, security-sbom.yml. Inputs and jobs are taken from each file's workflow_call section, following the existing security-trivy.yml format.
  • All sixteen workflows in .github/workflows/ are now documented, resolving the contradiction with AGENTS.md, which already listed them correctly.

Test plan

  • Every *.yml has a matching #### section in the README (no missing entries)
  • Every documented section refers to a file that exists (no phantom entries)
  • Documented inputs match each workflow's workflow_call.inputs for all six new sections
  • CI green

Comment thread .github/workflows/README.md Outdated
Comment thread .github/workflows/README.md
claude[bot]
claude Bot previously approved these changes Aug 7, 2026

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documentation is accurate and complete. Verified all 16 workflow files now have matching README sections (no phantom ci-go-action.yml, no missing entries), and every documented input/default/job name matches the corresponding workflow_call block for the six new sections. Left two minor, non-blocking nits (a slightly incomplete security-config description that omits the always-on Trivy config scan, and a Jobs-list consistency suggestion). Nothing blocking.

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update — the security-config.yml description is now clear about the always-on Trivy scan. One nit remains: release-go.yml and security-code.yml sections in the README still have no Jobs: list, while the other four sections added in this PR do. Please add them for consistency.

@sbaerlocher

Copy link
Copy Markdown
Member Author

Thanks — the first nit was a real gap and is fixed.

On the Jobs: lists for release-go.yml and security-code.yml, I'm declining, because the README's existing convention ties the list to job count, not to whether a section is new. Both workflows have exactly one job (goreleaser, analyze), and every single-job section in the file omits the list:

section jobs Jobs list
release-ansible-collection.yml 1 no
security-codeql.yml 1 no
ai-claude.yml 1 no
ai-claude-review.yml 1 no
release-go.yml (new) 1 no
security-code.yml (new) 1 no

The four pre-existing ones were not touched by this PR. Multi-job sections added here (ci-go, ci-lint, security-config, security-sbom) do carry a list, which matches ci-ansible-collection.yml, security-deps.yml and friends.

Adding the lists would make these two the only single-job sections in the file with one — a single-item list restating the heading. Happy to add them if the preference is to list jobs everywhere, but that should be a separate change covering all six for real consistency.

The README documented `ci-go-action.yml`, which does not exist — copying that
block yields a workflow resolution error — while six actual reusables were
missing entirely. All sixteen workflows are now documented from their
`workflow_call` inputs.

Signed-off-by: Simon Bärlocher <s.baerlocher@sbaerlocher.ch>
The `release-go.yml` and `security-code.yml` sections were the only ones
without a **Jobs:** list, which review feedback flagged as inconsistent
with the four sections added alongside them. Job names are taken from the
workflow files rather than inferred: `goreleaser`, and `analyze` as a
matrix over the `languages` input.

The rebase onto main brought in the three `self-*` workflows from #71,
which this README did not cover. They are deliberately absent from the
reusable sections above — they carry no `workflow_call` trigger and cannot
be called from another repository — so they get a short section of their
own stating that, rather than being listed as if consumers could use them.

Signed-off-by: Simon Bärlocher <s.baerlocher@sbaerlocher.ch>
@sbaerlocher
sbaerlocher force-pushed the fix/workflows-readme branch from dad7783 to 646f794 Compare August 7, 2026 17:57

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All raised issues have been addressed. The Jobs sections are now present for all workflow entries in the README including release-go and security-code. The three new self-* workflows look correct: self-merge.yml serializes tag moves with cancel-in-progress false and guards forward-only with an ancestry check; self-pull-request.yml and self-weekly-security.yml use appropriate minimal permissions. The .review-base/ sparse-checkout fix in ai-claude-review.yml is a solid security improvement. One cosmetic nit not worth blocking on: self-merge.yml annotates the checkout SHA as v7.0.1 while every other workflow uses v7 for the same SHA — harmless since Renovate tracks the SHA, but worth normalizing.

@sbaerlocher
sbaerlocher merged commit 483784f into main Aug 7, 2026
6 checks passed
@sbaerlocher
sbaerlocher deleted the fix/workflows-readme branch August 7, 2026 18:01
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