branch-sync-action

Keep a long-lived head branch in sync with a base branch. Merges automatically when it can, including the lockfile churn that defeats a plain git merge, and opens a pull request when a human is needed.

Built for the dependency-staging flow: a dependencies branch collects bot bumps, this action keeps it current with the trunk, and delivery to the trunk stays a single reviewed PR.

What it does

On each run it merges base into head:

• already in sync (nothing to merge, or the merge is empty) -> nothing to do
• clean merge -> push head
• only lockfiles conflict -> regenerate them against the merged manifest, push head
• a source file conflicts -> open a PR head -> base to resolve by hand

A successful run posts its outcome as an annotation, visible without reading the logs.

A lockfile conflict is the common case: bumps pile up on head while the trunk also moves. It is resolved without a human: the base side of the lock wins, then the lock is regenerated against the merged manifest (cargo fetch / npm install --package-lock-only --ignore-scripts), which restores whatever the head manifest requires. Base wins for two reasons: a bump lost on head is re-proposed by the bot on its next cycle, while a lockfile-only change on base is typically a security fix: once dropped, nothing re-applies it. A real source conflict is escalated to a PR so it is resolved on head, never on the trunk.

Usage

name: sync
on:
  push:
    branches: [master]
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

concurrency:
  group: branch-sync
  cancel-in-progress: false

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: voidmason/branch-sync-action@v1
        with:
          token: ${{ secrets.SYNC_TOKEN }}
          base: master
          head: dependencies

Inputs

Input	Required	Description
token	yes	PAT, see below.
base	yes	Branch to sync from.
head	yes	Branch to sync into.
name	no	Committer name. Defaults to the token owner.
email	no	Committer email. Defaults to the owner's noreply address.

Token

A PAT is required, not the default GITHUB_TOKEN: a push made with GITHUB_TOKEN does not trigger the downstream workflows on head (the lite CI that validates a regenerated lock), and on protected repositories it cannot push.

The merge and resolve commits are signed by the PAT owner: the committer is resolved from the token via voidmason/git-identity, unless an explicit name/email pair overrides it.

Permissions:

Permission	Why
Contents: read+write	fetch on checkout, push to head
Pull requests: read+write	list (dedup) and create the conflict PR
Workflows: write	only if a sync may carry changes under .github/workflows

A classic PAT with repo (plus workflow) covers the same.

Requirements

• The runner needs the toolchain for your lockfiles: cargo for Cargo.lock, npm for package-lock.json. ubuntu-latest ships both; add a setup step before this action if your project pins a specific toolchain.
• The head branch must already exist.

Notes

• The concurrency group in the usage example is load-bearing: the action pushes head without a lease, so two overlapping runs can race into a non-fast-forward rejection. Keep one sync per ref and do not cancel in progress. A rejected push goes red and self-heals on the next sync.
• A source conflict opens a PR and stops there: until that PR is merged, the whole sync (including lockfile bumps) is held - the merge is all-or-nothing. Resolve the PR to unblock.
• A lockfile that merges textually is pushed without being reconciled against the merged manifest: a clean text merge can still be semantically stale. Validating that is left to the downstream CI on head (the lite CI the PAT exists to trigger), same as for a regenerated lock.

License

MIT, see LICENSE.