🏓 Git Bounce

Tired of people ignoring your PR template?

Features

• ✅ Verify required sections exist in PR descriptions
• ✅ Ensure all checklist items are checked before merge
• ✅ Post helpful comments guiding contributors to complete requirements
• ✅ Fully customizable — define your own required sections and checkboxes
• ✅ Concurrency-safe — handles rapid PR updates gracefully

Quick Start

Add this workflow to your repository at .github/workflows/pr-checklist.yml:

name: PR Checklist

on:
  pull_request:
    types: [opened, edited, synchronize, ready_for_review]

concurrency:
  group: git-bounce-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  verify-checklist:
    name: Verify PR Checklist
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - name: Check PR Template
        uses: erinmikailstaples/git-bounce@v1
        with:
          required-sections: '["## Description", "## Checklist"]'
          required-checkboxes: '["I have tested my changes", "Ready for review"]'

Inputs

Input	Description	Required	Default
github-token	GitHub token for API access	No	${{ github.token }}
required-checkboxes	JSON array of checkbox text to require (case-insensitive)	No	''
required-sections	JSON array of section headers to require	No	''
fail-on-missing-template	Fail if PR body is empty	No	'true'
post-comment	Post verification results as a PR comment	No	'true'
comment-on-success	Post comment even when checks pass	No	'true'

Outputs

Output	Description
status	'success' or 'failure'
missing-sections	JSON array of missing required sections
unchecked-items	JSON array of unchecked required items
missing-items	JSON array of required items not found in PR

Examples

Basic Usage

Simplest setup — just fail if PR description is empty:

- uses: erinmikailstaples/git-bounce@v1

Documentation Repository

- uses: erinmikailstaples/git-bounce@v1
  with:
    required-sections: '["## Describe your changes", "## Related Issues", "## Checklist before requesting a review"]'
    required-checkboxes: |
      [
        "Is this ready for review",
        "This has deployed to a staging environment correctly",
        "I have reviewed my changes",
        "I have confirmed the content is technically accurate",
        "I have confirmed the content is free of typos or grammar errors",
        "I have reviewed the deployed version of my changes",
        "I have tested any code that is added or updated",
        "I have verified all images and videos are clear",
        "All checks have passed"
      ]

Code Repository

- uses: erinmikailstaples/git-bounce@v1
  with:
    required-sections: '["## What", "## Why", "## Testing"]'
    required-checkboxes: |
      [
        "Tests added/updated",
        "Documentation updated",
        "Ready for review"
      ]

Silent Mode (No Comments)

- uses: erinmikailstaples/git-bounce@v1
  with:
    post-comment: 'false'
    required-checkboxes: '["Ready for review"]'

Use Outputs for Custom Logic

- name: Check PR
  id: bounce
  uses: erinmikailstaples/git-bounce@v1
  with:
    required-checkboxes: '["Ready for review"]'
    post-comment: 'false'

- name: Custom handling
  if: steps.bounce.outputs.status == 'failure'
  run: |
    echo "Missing items: ${{ steps.bounce.outputs.missing-items }}"
    echo "Unchecked items: ${{ steps.bounce.outputs.unchecked-items }}"

PR Template Example

Here's an example PR template (.github/PULL_REQUEST_TEMPLATE.md) that works well with Git Bounce:

## Description

<!-- Describe your changes -->

## Related Issues

<!-- Link related issues: Fixes #123 -->

## Checklist

- [ ] I have tested my changes
- [ ] Documentation updated (if needed)
- [ ] Ready for review

Customizing for Your PR Template

Git Bounce works by matching text in your PR description. Here's how to configure it for your existing PR template:

Step 1: Identify Your Required Sections

Look at your PR template for markdown headers (lines starting with ##). Add each one you want to require to the required-sections input:

<!-- Your PR template has these sections: -->
## What Changed
## Why
## Testing Notes

# Your workflow config:
required-sections: '["## What Changed", "## Why", "## Testing Notes"]'

Step 2: Identify Your Required Checkboxes

Find the checkbox items in your template. You only need to include enough text to uniquely identify each checkbox — Git Bounce does partial, case-insensitive matching:

<!-- Your PR template has these checkboxes: -->
- [ ] I have added tests that prove my fix is effective
- [ ] I have updated the documentation accordingly
- [ ] My changes generate no new warnings

# You can use the full text or just the unique part:
required-checkboxes: |
  [
    "added tests",
    "updated the documentation",
    "no new warnings"
  ]

Step 3: Test Your Configuration

1. Create a test PR with an empty description — it should fail
2. Add the template but leave boxes unchecked — it should fail and list unchecked items
3. Check all boxes — it should pass

Tips

• Section matching is exact — "## Description" won't match ## description or ## Descriptions
• Checkbox matching is flexible — "tested my changes" matches - [x] I have tested my changes locally
• Don't include the checkbox syntax — use "Ready for review" not "- [ ] Ready for review"

How It Works

1. When a PR is opened, edited, or updated, Git Bounce checks the PR description
2. It verifies all required sections are present
3. It ensures all required checkboxes are checked (not just present)
4. It posts a comment summarizing the results
5. The workflow fails if any requirements aren't met, blocking merge

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.