feat(refs): fleet operational hygiene patterns#55
Merged
Conversation
Move four recurring fleet-operations practices out of per-user
CLAUDE.md files into the shared skill:
auto-merge-guide.md:
- 'CI Annotations — Always Check Before Declaring a PR Clean'
reviewdog-based linters (actionlint, shellcheck, yamllint,
CodeQL deprecation notices) can exit 0 while posting warning
annotations that don't appear in 'gh pr checks' or the PR
summary. Document the explicit annotations query
('gh api repos/.../check-runs/ID/annotations') and the
'fail_level: error' reviewdog input that converts warnings into
real failures.
- 'CI Re-runs Replay the Same Commit'
'gh run rerun' replays the ORIGINAL commit SHA, not HEAD. If you
push a fix then re-run a failed earlier workflow, the rerun still
fails. Explain the right sequence (push → wait for auto-run, or
find + rerun the LATEST run-id).
multi-repo-operations.md:
- 'Pre-Flight Per-Repo Checks'
Three pre-iteration guards that silently break fleet loops:
(1) not every repo uses 'main' — always gh api repos/X --jq
.default_branch; (2) archived repos reject writes with
cryptic permission errors — skip them or unarchive/re-archive;
(3) Contents API 'gh api -X PUT' returns HTTP 409 on any repo
requiring PRs / merge queue / signed commits, so half-a-fleet
gets updated when mixed. Default to one-commit PRs even for
tiny edits.
actionlint-guide.md:
- Sidebar note under Troubleshooting about yamllint's empty-lines
rule rejecting trailing blank lines — generators using
'echo "$CONTENT" > file.yml' add the blank. Prefer
'printf %s\\n'. Includes the 'xxd -p' check for verification.
merge-strategy.md:
- 'Rulesets cannot block merge on a pending review'
Neither branch protection nor rulesets support blocking merge
while Copilot (or any requested reviewer) hasn't finished
reviewing. Document the required_approving_review_count vs
required_review_thread_resolution non-equivalence and the
custom-status-check workaround.
Signed-off-by: Sebastian Mendel <sebastian.mendel@netresearch.de>
Contributor
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
Contributor
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
There was a problem hiding this comment.
Pull request overview
Adds shared “fleet operational hygiene” guidance to the github-project skill reference docs, consolidating recurring operational pitfalls and safer default patterns for multi-repo automation.
Changes:
- Documented per-repo pre-flight checks for fleet loops (default branch, archived repos, Contents API vs protections).
- Added guidance on CI annotation visibility + making reviewdog warnings fail, and on Actions reruns replaying the original SHA.
- Documented limitations of rulesets/branch protection around pending reviews + a custom status-check workaround; added yamllint trailing-blank-line pitfall and generator fix.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| skills/github-project/references/multi-repo-operations.md | Adds “Pre-Flight Per-Repo Checks” section to prevent common fleet-loop failures. |
| skills/github-project/references/merge-strategy.md | Adds ruleset/branch-protection limitation note and a suggested status-check workaround. |
| skills/github-project/references/auto-merge-guide.md | Adds CI annotations visibility checks and correct guidance for rerunning the latest Actions run. |
| skills/github-project/references/actionlint-guide.md | Adds yamllint trailing-blank-line failure mode and generator recommendation. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Merged
CybotTM
added a commit
that referenced
this pull request
May 15, 2026
## Release v2.14.0 Minor release. `.claude-plugin/plugin.json` and `skills/github-project/SKILL.md` frontmatter `metadata.version` were already synced to `2.14.0` on `main` via [#74](#74) — this PR is the empty release marker that closes the v2.13.1 → v2.14.0 window and triggers the signed-tag release. ### Highlights since v2.13.1 - **`agentic-workflows` reference** documenting `gh-aw` and `awf` workflow-as-prompt tooling for autonomous GitHub Actions — new patterns for running AI agents on PRs/issues without bespoke wiring ([#75](#75)). - **AI reviewer pushback patterns** — handling Copilot/Sourcery review comments that disagree with the codebase intent, including when to defer and when to push back ([#66](#66), [#74](#74)). - **PR-merge / branch-protection / CodeQL gotchas** documented, plus auto-detection of allowed merge strategy in the `--delete-branch` snippet so the recipe doesn't break on repos with merge-commit-only policies ([#69](#69), [#71](#71), [#72](#72)). - **GraphQL `Repository.mergeQueue`** for queue detection — replaces a brittle REST probe ([#70](#70)). - **Assessment checkpoints overhaul**: new GH-34/GH-35/GH-36, follow_uses delegation for CodeQL/Scorecard, org_provides for community-health files, broader licence/Dependabot/workflow targets, plus reusable-workflow-pitfalls reference. Multiple false-positive findings demoted to `info` to reduce assessment noise ([#56](#56), [#57](#57), [#58](#58), [#59](#59), [#60](#60), [#61](#61), [#62](#62), [#63](#63), [#64](#64), [#65](#65), [#73](#73)). - **npm distribution** — the skill now also ships via `@netresearch/agent-skill-coordinator` ([#54](#54), [#55](#55)). - **Release pipeline hardening** — dropped the deprecated `with: bump:` block + `workflow_dispatch.bump` input so releases happen exclusively via locally-signed tags, plus SLSA-provenance permissions on the caller ([#52](#52), [#53](#53)). ### Release plan After merge: tag main with a signed annotated tag, push, the `skill-repo-skill` reusable workflow publishes archives + SHA256SUMS with cosign + SLSA attestation, then narrative notes get applied via `gh release edit ... --notes-file`.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Move four recurring fleet-ops practices from per-user CLAUDE.md into the shared skill.
auto-merge-guide.mdgh pr checks. Document the explicit annotations query +fail_level: errorreviewdog input to make warnings fail the job.gh run rerunreplays the ORIGINAL sha, not HEAD; push → wait for auto-run OR find + rerun the LATEST run-id.multi-repo-operations.mdmain), (2) archived-repo skip (writes return cryptic permission errors), (3) Contents API vs branch protection (-X PUTreturns 409 when PRs/signing required — half-a-fleet updates leave you in split-brain).actionlint-guide.mdempty-linesrejects trailing blanks on workflow files. Generators usingecho "$CONTENT" > file.ymladd the blank; useprintf '%s\n'. Includes thetail -c 2 | xxd -pverification.merge-strategy.mdrequired_approving_review_countandrequired_review_thread_resolutionare not equivalent to "wait for Copilot to finish". Document the non-equivalence and the custom-status-check workaround.Test plan