Skip to content

docs: add workflow trigger conventions reference#57

Merged
DevSecNinja merged 1 commit intomainfrom
docs/workflow-trigger-conventions
May 1, 2026
Merged

docs: add workflow trigger conventions reference#57
DevSecNinja merged 1 commit intomainfrom
docs/workflow-trigger-conventions

Conversation

@DevSecNinja
Copy link
Copy Markdown
Owner

Why

We've converged on a consistent set of GitHub Actions trigger / concurrency / IRM patterns across truenas-apps and dotfiles. Without a written reference each new repo (or each future me) re-derives them — and gets the subtle traps wrong (event_name == 'push' silently skipping workflow_dispatch reruns; release: created not firing reliably from GitHub App tokens; etc.).

What

New page docs/workflow-trigger-conventions.md covering:

  • Default trigger surface (pull_request-only for CI; when push: main is justified).
  • Why we don't use pull_request_target casually.
  • Concurrency: cancellable for PR-validation, non-cancellable for release/docs-publish; reusable workflows defer to caller.
  • Why we don't gate on draft PRs (release-please opens drafts by design).
  • Why we avoid path filters on required checks.
  • notify-irm rules: gate on github.ref == 'refs/heads/main' only; do not also gate on github.event_name == 'push'; don't add to PR-only CI workflows.
  • Release flow with release-please: draft-publish, tag-push trigger (NOT release: created), Immutable Releases compatibility.
  • Quick-reference table for common workflow types.

Plus:

  • README.md: new table row linking to the doc.
  • docs/release-please-onboarding.md: cross-link in the release flow section.

Motivating PRs

Codifies the org-wide rules we converged on across truenas-apps and dotfiles: pull_request-only as default for CI; push:main only when there's post-merge-only work; concurrency cancellation patterns; notify-irm gating (do NOT gate on github.event_name == 'push'); tag-push vs release:created for release-publish workflows; release-please draft-publish flow.

Cross-linked from release-please-onboarding.md and indexed in README.md.

Real motivating PRs cited inline: dotfiles#263, #265, #266; truenas-apps#317, #325.
@DevSecNinja DevSecNinja merged commit d26e9d3 into main May 1, 2026
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