require-approved-issue

A GitHub Action that enforces an "issue-first" contribution workflow. PRs from outside contributors must reference a GitHub issue that has received a reaction (default: thumbs-up) from someone with write access to the repository. PRs that don't meet this requirement are automatically closed or fail a status check.

Why?

Open-source maintainers often receive PRs for work that was never discussed or approved. This action prevents that by requiring contributors to:

1. Open an issue describing the proposed change
2. Wait for a maintainer to approve the issue (via a reaction)
3. Reference the approved issue in the PR body (e.g. Fixes #123)

Maintainers and other users with write access are automatically exempt.

Usage

Important: Use pull_request_target instead of pull_request as the trigger. PRs from forks (the primary use case for this action) receive a read-only GITHUB_TOKEN with pull_request, which prevents the action from posting comments or closing the PR. pull_request_target runs in the context of the base repository with full permissions. This is safe because the action does not check out or execute any code from the PR.

Close mode (default — strictest)

name: Require Approved Issue
on:
  pull_request_target:
    types: [opened, reopened]

permissions:
  pull-requests: write
  issues: read

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: robzolkos/require-approved-issue@v1
        with:
          reaction: '+1'
          exempt-authors: 'dependabot[bot],renovate[bot]'

PRs from outside contributors without an approved linked issue are immediately closed with a comment explaining why. The contributor must get the issue approved by a maintainer first, then reopen the PR (or open a new one).

Status check mode (softer)

name: Require Approved Issue
on:
  pull_request_target:
    types: [opened, reopened, synchronize]

permissions:
  pull-requests: write
  issues: read

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: robzolkos/require-approved-issue@v1
        with:
          mode: 'status-check'
          reaction: '+1'
          exempt-authors: 'dependabot[bot],renovate[bot]'

PRs from outside contributors without an approved linked issue get a failing status check but remain open. The contributor can update their PR body to link an approved issue and push a new commit to re-trigger the check.

Pair this with a branch protection rule requiring this check to pass before merge.

The synchronize event is included so the check re-runs when the contributor pushes new commits after updating their PR description.

Mode

The mode input controls what happens when a PR fails validation:

Mode	Behavior	Best for
close (default)	Closes the PR with a comment	Strict "issue-first" workflows; avoids wasting review time on unapproved work
status-check	Fails the check but leaves the PR open	Teams that prefer a softer approach; lets contributors fix their PR in place

Inputs

Input	Required	Default	Description
github-token	no	${{ github.token }}	Token for API calls
mode	no	close	close or status-check (see above)
reaction	no	+1	Reaction type to look for (+1, heart, rocket, etc.)
no-issue-message	no	(built-in)	Comment when PR has no linked issue
no-approval-message	no	(built-in)	Comment when linked issue lacks approval
exempt-authors	no	""	Comma-separated usernames exempt from this check
exempt-label	no	""	PRs with this label skip the check

Outputs

Output	Description
approved	"true" or "false"
linked-issues	Comma-separated issue numbers found in PR body

How it works

1. When a PR is opened or reopened, the action runs
2. If the PR author has write access to the repo, the check is skipped
3. If the PR author is in exempt-authors or the PR has the exempt-label, the check is skipped
4. The action parses the PR body for closing keywords (Fixes #N, Closes #N, Resolves #N)
5. For each linked issue, it checks if any user with write access has reacted with the configured reaction
6. If at least one linked issue is approved, the PR passes
7. Otherwise, a comment is posted and the PR is closed (or the check fails, depending on mode)

First-time contributors

GitHub requires a maintainer to approve workflow runs from first-time contributors before any actions execute. This means a maintainer will already be reviewing the PR before this action runs — giving you an opportunity to manually close it or approve the run and let the action handle it.

Once a contributor has had their first workflow run approved, all subsequent PRs from them will trigger the action automatically with no manual step.

License

MIT