In the modern software development lifecycle, the pull request serves as the primary gatekeeper for code quality and architectural consistency. However, default GitHub settings often allow merges even when specific conditions are unmet, leading to fragmented histories, inconsistent states, and deployment risks. Advanced repository governance requires moving beyond simple status checks to implement strict blocking mechanisms. This involves leveraging specialized GitHub Actions, configuring branch protection rules, and utilizing time-based or content-based restrictions to ensure that only valid, timely, and structurally sound changes enter the main codebase. The following analysis details three distinct methodologies for blocking merges: preventing merge commits, enforcing branch protection workflows, and restricting merges based on time zones and holidays.
Blocking Merge Commits
Merge commits—commits generated when one branch is merged into another—can pollute the git history, making linear development difficult and complicating bisect operations. The Morishiri/block-merge-commits-action provides a mechanism to prevent these commits from being merged into the target branch. When this action runs on a pull request, it inspects the commit history. If any commit within the pull request is identified as a merge commit, the action sets the check status to error, effectively blocking the merge.
A critical technical limitation exists within this implementation: GitHub's API returns only the first 250 commits of a pull request. Consequently, if a pull request contains more than 250 commits, merge commits appearing beyond this threshold may remain undetected. To implement this, developers must define a workflow that triggers on pull_request events and utilizes the action with appropriate permissions.
yaml
on: pull_request
name: Pull Request
permissions:
pull-requests: read
jobs:
message-check:
name: Block Merge Commits
runs-on: ubuntu-latest
steps:
- name: Block Merge Commits
uses: Morishiri/block-merge-commits-action@v2
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
For repositories utilizing fine-grained permissions, the workflow or job must explicitly declare pull-requests: read to ensure the action can inspect the pull request details. It is important to note that this specific action is not certified by GitHub, meaning it relies on community maintenance rather than official GitHub endorsement. To make this blocking mechanism effective, administrators must also configure branch protection rules to require this specific status check to pass before allowing a merge.
Configuring Branch Protection Rules
While individual actions provide the detection logic, branch protection rules provide the enforcement mechanism. Without these rules, a failing action merely generates a warning; the merge can still proceed if a user has sufficient permissions to bypass checks. To prevent this, administrators must navigate to the repository settings, specifically the "Branches" section, and establish rules for the main branch.
The configuration requires enabling the checkbox labeled "Require status checks to pass before merging." For enhanced integrity, enabling "Require branches to be up to date before merging" is recommended to prevent stale code from being merged. After enabling these options, specific GitHub Action steps (such as a build job) must be selected to define which checks are mandatory.
Consider a workflow for Python unit tests. The job name, in this case build, must match the identifier used in the branch protection settings.
yaml
name: Python Unit Tests
on:
pull_request:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.7'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -r dev-requirements.txt
- name: Test with pytest
run: |
pytest --verbose
Once the job is selected in the branch protection interface, saving these changes ensures that the build job must return a success status before the merge button becomes active. This creates a hard gate that cannot be bypassed by standard users, ensuring code quality is enforced at the infrastructure level.
Time-Based Merge Restrictions
Organizations often need to restrict merging activities during off-hours, weekends, or public holidays to reduce emergency maintenance and ensure that changes are reviewed during working hours. The yykamei/block-merge-based-on-time action enables granular control over when merges are permitted. This is particularly useful for preventing late-night emergency merges or ensuring compliance with regional work schedules.
The workflow must trigger on various pull request events, including opened, reopened, synchronize, labeled, unlabeled, and ready_for_review. Additionally, a cron schedule (*/30 * * * *) can be used to periodically evaluate open pull requests.
yaml
name: Block Merge Based on Time
on:
pull_request:
types:
- opened
- reopened
- synchronize
- labeled
- unlabeled
- ready_for_review
schedule:
- cron: "*/30 * * * *"
jobs:
block:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read
statuses: write
steps:
- uses: yykamei/block-merge-based-on-time@main
id: block
with:
timezone: Pacific/Honolulu
after: "17:30, 16:30 on Monday"
before: 09:00
base-branches: "(default)"
prohibited-days-dates: "Sunday, 2021-10-01, 2021-12-29/2022-01-04, H:United States, BH:United States"
custom-holidays-path: "./custom-holidays.json"
- run: echo pr-blocked=${{ steps.block.outputs.pr-blocked }}
if: github.event_name == 'pull_request'
This action supports several configuration inputs. The timezone parameter defines the local time zone for evaluation. The prohibited-days-dates parameter allows for complex scheduling, such as blocking merges on Sundays, specific dates, or regional holidays. For instance, H:Japan blocks merges on Japanese public holidays, such as National Foundation Day. If a custom JSON file is provided via custom-holidays-path, it overrides the built-in holiday lists for the specified country codes. The action outputs a boolean string pr-blocked indicating whether the pull request is currently blocked. Draft pull requests are automatically skipped, outputting false to avoid unnecessary blocking of unready code.
Community Insights and Workflow Patterns
Community discussions highlight the importance of consolidating multiple checks into a single "gate" check, particularly in matrix-heavy workflows. Users have reported issues where pull requests are automatically merged before all matrix jobs have completed, leading to inconsistent states. The recommended pattern involves creating a single check that summarizes the status of all underlying jobs. This approach keeps the pull request interface clean and provides actionable feedback rather than a wall of individual job results.
Furthermore, users have noted confusion regarding why merges still occur despite failing checks. This is typically due to missing branch protection rules that enforce the required status checks. If a check is never scheduled or if branch protection is not configured to require that specific check, the merge gate remains open. Implementing a GitHub App or a consolidated action that monitors architecture drift or change-risk provides a more robust solution than relying on fragmented job statuses.
Conclusion
Effective merge governance in GitHub requires a multi-layered approach combining content validation, infrastructure enforcement, and temporal restrictions. By blocking merge commits, administrators maintain a clean, linear git history. By configuring branch protection rules, they ensure that unit tests and build jobs pass before any code enters the main branch. By implementing time-based restrictions, organizations align development activities with operational hours and regional holidays, reducing the risk of unreviewed or off-hours changes. Together, these strategies create a robust framework for maintaining code integrity, ensuring that every merge is intentional, verified, and timely.