feat(references): bash patterns inside workflow run: steps#53
Merged
Conversation
Codify the recurring shell-scripting failure modes we hit during the
netresearch go-workflow standardization so future reusable-workflow
authors can skip the fleet-wide incidents we already paid for:
- 'set -e + $(cmd)' aborts before custom ::error:: annotations —
wrap in 'if ! VAR=$(cmd); then' (`if` is exempt from set -e).
- 'grep ... | grep -q .' pipelines race under set -o pipefail when
the reader exits early; SIGPIPE on the producer flips the whole
pipeline to non-zero. Use command substitution or 'find … -quit'.
- '2>&1' merged into a captured variable lets stderr warnings
corrupt downstream ldflags / release metadata. Keep stderr out
of BUILD_TS etc.
- hashFiles() is only valid in step-level expressions. Using it
in top-level job 'with:' fails validation, and GitHub then
runs the workflow on every trigger regardless of 'on:' match
with a 'workflow file issue' exit.
- A file that fails validation runs on every trigger (not just
those matching 'on:') — explain the gh run list hallmark
('name: .github/workflows/foo.yml') so diagnosis is fast.
- Reusable workflow jobs must declare permissions <= the
caller's grant or GitHub returns startup_failure fleet-wide.
Add a 'CALLER REQUIREMENTS' block convention for reusables.
Cross-link from SKILL.md's References table and from
reusable-workflow-security.md.
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 a new GitHub Project Skill reference documenting recurring Bash/shell pitfalls in GitHub Actions run: steps, and links it from the skill’s References table so workflow authors can find it alongside existing actionlint/security guidance.
Changes:
- Added
references/workflow-bash-patterns.mdwith incident-driven patterns and fixes forset -e,pipefail, stderr capture, expression context, workflow validation, and reusable-workflow permissions. - Updated
skills/github-project/SKILL.mdto link the new reference (andreusable-workflow-security.md) in the References table.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| skills/github-project/references/workflow-bash-patterns.md | New reference doc describing common failure modes and recommended shell patterns for Actions run: steps. |
| skills/github-project/SKILL.md | Adds links to the new reference (and reusable workflow security) in the References table. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
CybotTM
force-pushed
the
feat/workflow-bash-patterns
branch
2 times, most recently
from
7dfcc89 to
36e532b
Compare
…kflow-security row (already referenced via cross-link in the new file) Signed-off-by: Sebastian Mendel <sebastian.mendel@netresearch.de>
CybotTM
force-pushed
the
feat/workflow-bash-patterns
branch
from
36e532b to
d7066dd
Compare
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
New reference
references/workflow-bash-patterns.mdcodifying the recurring shell-scripting failure modes we hit during the netresearch go-workflow standardization (April 2026). Every entry has caused a fleet-wide incident at least once.What's covered
::error::never firesset -eaborts onVAR=$(cmd)before the diagnostic runsset -o pipefail+ early-exit reader2>&1merged into a captured variablehashFiles()/steps.*in top-levelwith:name: .github/workflows/foo.yml)startup_failureafter template changeEach entry includes the bug, the fix, and real-incident framing. Cross-linked from
SKILL.mdReferences table and referenced as a companion toactionlint-guide.md/reusable-workflow-security.md.Why now
During Go workflow standardization we hit all six of the above — some repeatedly, because we fixed the symptom without writing down the underlying pattern. Future authors of reusable workflows should start from this file.