Skip to content
Nitjsefnie-ActionsPublic

About

Reusable GitHub pull-request template and issue-assignment admission gate

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

236 Commits

Folders and files

Repository files navigation

Pull request admission gate

A SHA-pinnable GitHub composite action that checks pull-request descriptions against the consumer repository's template and assigned issues. When a description fails, it comments with the reasons and fails its own check until an edit fixes it; it never closes or reopens a PR.

Usage

Pin the action to a reviewed full commit SHA from this repository. The # vX.Y.Z comment after the pin names the reviewed release carrying that SHA; the version comment is documentation, never the pin itself — do not substitute a mutable branch or tag. Dependabot is expected to propose moving this repository's own workflow pin — SHA and version comment together — when a release is cut. The pin-sync test holds this example and the workflow to the same reviewed SHA under the same version comment.

name: pr gate
# pull_request_target: a fork's pull_request token is read-only, so its
# comment would silently do nothing. The pinned action reads the template at
# the PR's base SHA and runs no pull-request code. synchronize re-runs the
# gate on every push, so its check attaches to each new head.
on: # zizmor: ignore[dangerous-triggers]
  pull_request_target:
    types: [opened, edited, reopened, synchronize, ready_for_review]
permissions:
  contents: read
  issues: read
  pull-requests: write
concurrency:
  group: pr-gate-${{ github.event.pull_request.number }}
  cancel-in-progress: false
jobs:
  gate:
    # Bot-authored pull requests are not gated, and a draft is checked when
    # it is marked ready for review. GitHub reports a skipped job's check as
    # success, so neither blocks a merge.
    if: >-
      github.event.pull_request.user.type != 'Bot'
      && github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: Nitjsefnie-Actions/pr-gate@20c1402a52bbe3db1a2504160295469e4a31c142 # v3.0.4
        with:
          github-token: ${{ github.token }}
          repository: ${{ github.repository }}
          pull-request-number: ${{ github.event.pull_request.number }}
          pull-request-author: ${{ github.event.pull_request.user.login }}
          require-commit-attribution: 'true'

No consumer checkout is needed. The action executes only its own code through github.action_path. It reads the current PR, fetches the consumer template through GitHub's contents API at that PR's base commit SHA, and asks GitHub to render the body. It never checks out or executes PR-head code. Inputs enter the process through environment variables, not shell-source interpolation.

The action brings its own Python. The runner needs only Bash and GitHub CLI gh. GitHub-hosted runners provide these tools. Runtime Python code uses only the standard library. For a self-hosted runner, install the tools before this step.

Input Meaning
github-token Required token with the permissions in the example.
repository Required consumer repository, owner/name.
pull-request-number Required PR number.
pull-request-author Required author login.
require-commit-attribution Optional; defaults to false. Only true (case-insensitive, surrounding whitespace ignored) enables the commit check.
conventional-commits Optional; defaults to true. Only false (case-insensitive, surrounding whitespace ignored) disables the Conventional Commits check.
template-path Optional consumer path; defaults to .github/PULL_REQUEST_TEMPLATE.md.

Admission rules

The template uses ## section headings followed by instruction comments tagged Required, Conditional, or Optional, without case sensitivity. Required sections must appear. Included sections must have visible content, known names, and template order. Duplicate/invented sections and retained template instruction comments are rejected. The shipped PR template is an example consumer contract.

GitHub-rendered HTML is the sole authority for body section boundaries. Setext headings, ordinary Markdown headings, and HTML headings follow their rendered structure; heading-like text in code stays text. Footer, when present, must be one final visible attribution line:

Generated by GPT-6 Astra (implementation, testing), Another Model (review)

Bugs Discovered, when present, contains only rendered unordered-list items whose visible text is #N Literal issue title. Every number must identify an existing issue in the consumer repository, and the title must equal GitHub's title exactly. Pull-request numbers, narrative entries, and mismatched titles fail. Equivalent Markdown bullet markers are accepted. Escape Markdown metacharacters when necessary to preserve an issue title's literal visible text.

At least one issue named in Related Issues and Pull Requests or by a body-wide closing reference must be assigned to the PR author. Every closing issue must be assigned to that author. Mere bug-list pointers do not substitute for this assignment requirement. At most 20 distinct references are checked, sharing one lookup cache between assignment and bug-title validation. Larger sets receive a corrective comment.

The gate maintains one bot-owned marker comment. Any failing check (layout, content, claim, commit attribution or commit subject, including more than twenty references or no checked reference at all) writes the reasons into that comment and fails the gate's own check; the PR stays open. Require the gate's job check in a ruleset to hold the merge until every check passes. Every edit of or push to a non-draft PR by a human author re-runs the gate, and once all conditions pass it rewrites its comment to say so and its check passes. A closed or merged PR is left alone: its author reopens it, or opens a fresh PR from the same branch when GitHub refuses that reopen. The gate re-reads the PR before each comment write and aborts when it was closed or merged meanwhile. Assignment changes alone do not trigger the workflow: edit or push to the PR to request another check.

Commit attribution is an opt-in admission rule. When enabled, the gate checks every commit when the PR carries at most 250; a PR with more commits is refused because the action cannot verify it. Each commit's author and committer must resolve to a GitHub account and be the PR author, GitHub's web-flow account, an account with write, maintain, or admin push permission, or have a Co-Authored-By: trailer on that same commit whose email resolves to the PR author. An unlinked author or committer email is refused. A human coauthor trailer whose email cannot be resolved is also refused. A trailer email whose local part is exactly noreply (case-insensitive), such as noreply@anthropic.com, noreply@z.ai, or noreply@openai.com, is treated as a model/vendor trailer and is outside this rule.

Commit subjects follow Conventional Commits 1.0.0 unless conventional-commits is false. Each commit's first line must read type(scope)!: description, and a commit with more than one parent is not checked. The scope and ! are optional, a scope is one or more characters other than parentheses, neither starting nor ending with whitespace (inner spaces are allowed), the type is one of build, chore, ci, docs, feat, fix, perf, refactor, revert, style or test in any letter case, a colon and one space follow, and the description holds a non-whitespace character. The gate's comment lists each failing commit's short SHA and subject and names this format. The check reads only the subject: whether the type and ! fit the change stays with review. It shares the commit list with the commit-attribution check, fetched once when both are on, and a PR with more than 250 commits is refused with a reason naming each check that cannot verify it.

The email lookup searches GitHub's public commit index; an email used only in private repositories remains unresolvable, so a human coauthor trailer using it is refused. GitHub's collaborator-permission endpoint returns 403 when the action token cannot view that account's permission. The gate treats 403 and 404 as no push access, so the push-access exemption is available only when the consumer's token can read collaborator permissions. The example token is read-only for repository contents and issues (with pull-request write access for the gate's comment), so this exemption may fail closed for maintainers unless the consumer grants the needed access. With the input off, the gate makes no collaborator, user, or commit-search requests, and it reads the commit list only for the Conventional Commits check; with both checks off, it makes no commit-list request either.

The run's exit code states the outcome. Zero: the description passes and is covered by its claimed issue, or the PR is merged or not open. Exit 2: the gate found defects, such as a failing commit subject, and commented on them; it prints one stderr line with the same reasons the comment carries, each unprintable character escaped. Analysis and API failures exit 1 with pr gate failed: ... on stderr. Consumer repositories remain responsible for assigning issues and for a ruleset that requires the gate's check.

Development and community

See CONTRIBUTING.md for setup, exact checks, security and TDD requirements, and commit attribution. Use the shipped issue and PR templates. Participation follows Contributor Covenant 2.1. Report vulnerabilities privately as described in SECURITY.md.

The parser and controller originate in the Daedalus/Overflow gate; captured GitHub renderings are retained as regression fixtures. Code is MIT licensed.

About

Reusable GitHub pull-request template and issue-assignment admission gate

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages