A powerful GitHub Action for automatically managing staging branches with configurable sync, reset, and PR labeling functionality.

Features

• ✅ Auto-sync staging branch - Automatically syncs commits from main branch to staging branch
• ✅ Scheduled reset - Resets staging branch to main on a configurable schedule (default: every Sunday at midnight)
• ✅ PR labeling - Automatically stage PRs when labeled with to-stage, and mark them as staged when complete
• ✅ Smart label management - Removes staged labels when PRs are removed from staging or when commits are no longer staged
• ✅ Manual sync detection - Detects when commits are manually added to staging and syncs if needed
• ✅ Reports failures on the PR - Every failure to stage a PR is commented on that PR, with the git output and a link to the run
• ✅ Verified staging - Confirms the staging branch really contains the PR before marking it staged, and retries a push lost to a concurrent update
• ✅ Fully configurable - All branch names, labels, and behaviors are configurable

Usage

Create a workflow file (e.g., .github/workflows/auto-staging.yml) in your repository:

name: Auto Staging

on:
  # Scheduled reset every Sunday at midnight
  schedule:
    - cron: '0 0 * * 0'  # Sunday midnight UTC
  # Trigger on push to main or staging
  push:
    branches:
      - main
      - staging
  # Trigger on PR events (including label events)
  pull_request:
    branches:
      - main
    types: [opened, reopened, synchronize, labeled, unlabeled]
  # Allow manual triggering
  workflow_dispatch:

jobs:
  auto-staging:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}
      
      - name: Run Auto Staging
        uses: Plexverse/auto-staging@v1
        with:
          main_branch: 'main'
          staging_branch: 'staging'
          to_stage_label: 'to-stage'
          staged_label: 'staged'
          github_token: ${{ secrets.GITHUB_TOKEN }}
          enable_auto_sync: 'true'
          enable_scheduled_reset: 'true'
          enable_pr_labeling: 'true'

Configuration Options

All inputs are optional and have sensible defaults:

Input	Description	Default	Required
main_branch	Name of the main branch	main	No
staging_branch	Name of the staging branch	staging	No
to_stage_label	Label to trigger staging a PR	to-stage	No
staged_label	Label to mark a PR as staged	staged	No
github_token	GitHub token for API calls	-	Yes
reset_schedule	Cron schedule for resetting staging branch	0 0 * * 0	No
enable_auto_sync	Enable auto-sync of main branch commits to staging	true	No
enable_scheduled_reset	Enable scheduled reset of staging branch	true	No
enable_pr_labeling	Enable PR labeling functionality	true	No

How It Works

Auto-Sync

When commits are pushed to the main branch, the action automatically:

1. Checks if there are new commits in main that aren't in staging
2. Merges those commits into staging
3. Updates PR labels if any staged PRs are affected

Scheduled Reset

On the configured schedule (default: Sunday midnight UTC), the action:

1. Resets the staging branch to match main exactly
2. Removes staged labels from all PRs that were affected by the reset

PR Labeling

When a PR is labeled with the to-stage label:

1. The action fetches the current PR state from the API (to get up-to-date labels)
2. Verifies the PR currently has the to-stage label
3. Merges the PR into the staging branch and pushes it
4. Re-fetches staging and verifies it actually contains the PR head commit
5. Adds the staged label to the PR and removes the to-stage label
6. If anything fails, the action posts a comment on the PR explaining what went wrong and does not add the staged label

If the push is rejected because something else updated staging at the same time, the action re-syncs and retries (3 attempts) before giving up and commenting. The staged label is only applied once the PR head commit is confirmed to be an ancestor of the remote staging branch, so a green run always means the change really is staged.

Note: The action fetches current PR labels from the API (not from the event payload) to handle labels added after the PR was opened, since github.event.pull_request.labels only contains labels from when the PR was first created.

When a PR is reopened or synchronized:

1. The action fetches the current PR state from the API
2. Checks if the PR currently has the staged label
3. Verifies if all PR commits are still in the staging branch
4. Removes the staged label if commits are no longer staged

Manual Sync Detection

When commits are manually pushed to the staging branch:

1. The action detects the push event
2. Checks if there are commits in main that aren't in staging
3. Automatically syncs those commits if found

Examples

Custom Branch Names

- name: Run Auto Staging
  uses: Plexverse/auto-staging@v1
  with:
    main_branch: 'master'
    staging_branch: 'develop'
    github_token: ${{ secrets.GITHUB_TOKEN }}

Custom Labels

- name: Run Auto Staging
  uses: Plexverse/auto-staging@v1
  with:
    to_stage_label: 'ready-for-staging'
    staged_label: 'in-staging'
    github_token: ${{ secrets.GITHUB_TOKEN }}

Disable Scheduled Reset

- name: Run Auto Staging
  uses: Plexverse/auto-staging@v1
  with:
    enable_scheduled_reset: 'false'
    github_token: ${{ secrets.GITHUB_TOKEN }}

Custom Reset Schedule

- name: Run Auto Staging
  uses: Plexverse/auto-staging@v1
  with:
    reset_schedule: '0 2 * * 1'  # Every Monday at 2 AM UTC
    github_token: ${{ secrets.GITHUB_TOKEN }}

Disable PR Labeling

- name: Run Auto Staging
  uses: Plexverse/auto-staging@v1
  with:
    enable_pr_labeling: 'false'
    github_token: ${{ secrets.GITHUB_TOKEN }}

Permissions

The action requires the following permissions:

• contents: write - To push changes to the staging branch
• pull-requests: write - To add/remove labels on PRs
• issues: write - To post comments on PRs (PRs are treated as issues in the GitHub API)

Requirements

• jq - The action will automatically install jq if it's not available
• Git with proper authentication configured
• A GitHub token with appropriate permissions

Troubleshooting

Staging branch doesn't exist

The action will automatically create the staging branch from the main branch if it doesn't exist.

Merge conflicts

If a merge conflict occurs when syncing or staging a PR, the action will:

• Log a warning
• Abort the merge
• Not push any changes
• Post a comment on affected PRs explaining the conflict and how to resolve it
• For PR staging, not add the staged label
• Fail the job, so the run shows up red rather than silently passing

A PR was never staged and nothing was reported

This was possible in versions before the failure-reporting fix: a conflicted merge was mistakenly read as a success, so the run went green, the PR was labelled staged, and no comment was posted even though staging had not moved. Re-run against the current v2 tag, which fails the job and comments on the PR instead. If a comment still does not appear, check the run log for GitHub rejected the comment - that means the token is missing issues: write / pull-requests: write.

PR labels not updating

Ensure that:

• The enable_pr_labeling input is set to true
• The GitHub token has pull-requests: write permission
• The labels (to-stage and staged) exist in your repository

License

This action is provided as-is. Modify as needed for your use case.