A GitHub Action that keeps your forks up to date with their upstream repositories, but only moves a fork to an upstream commit after every CI check on that commit has passed.
Other fork-sync tools copy whatever is on upstream main right now, even if its CI is red
or still running. This one waits for green, so your fork's main is always a commit that
upstream's own CI approved.
- Syncs any number of forks from one workflow.
- Fast-forward only. A fork with commits of its own is reported and never overwritten.
- Works for linked forks and for plain copies of a repo that GitHub doesn't show as forks.
- Python standard library plus the
ghCLI, both already on GitHub-hosted runners.
For each repo it walks the upstream branch's recent history, newest first, and picks the first commit that:
- was itself the tip of the upstream branch (first-parent history, so commits from merged PR branches don't count),
- is at least
min-age-minutesold (default 10), so every workflow has had time to start, - has at least one check run or commit status,
- has every check run finished as success, skipped or neutral, with nothing
failed, cancelled, timed out or still running (names in
ignore-checks, and runs of workflows started by an event inignore-events, are left out), - has every GitHub Actions workflow run for it finished the same way. This catches a
workflow that was cancelled, or is still queued, before any of its jobs reported a check
run, which would otherwise leave only the other workflows' passing checks to look at.
Workflows started by an
ignore-eventsevent or whose name matchesignore-checksare left out, and so is a workflow that is unfinished or failed only because of an ignored job, - has a combined commit status of success, if it has any statuses.
The fork's branch is then fast-forwarded to that commit. If no newer commit qualifies yet, the fork stays where it is and the next run tries again.
With docs-paths set, newer commits that have no checks and only change matching files
(say *.md or .coderabbit.yaml) are taken along too, as long as they sit directly on top
of that green commit (or of the fork's current commit) with nothing failed, running or too
new in between.
Expect some waiting: busy projects often cancel CI on a commit when a newer push arrives,
and commits that only touch docs are often skipped by paths: filters, so they have no
checks. Those commits are passed over, and the fork moves on the next fully green one.
The default GITHUB_TOKEN can't write to other repositories, so the action needs a
fine-grained personal access token:
- Go to Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token (https://github.com/settings/personal-access-tokens/new).
- Resource owner: the account or organization that owns your forks.
- Repository access: Only select repositories, and pick every fork you want synced.
- Repository permissions:
- Contents: Read and write (to move the branch),
- Workflows: Read and write (GitHub requires this whenever an upstream commit
changes files in
.github/workflows), - Metadata: Read-only (required, selected automatically).
- Generate it and copy the value.
Create a repository to run the sync from (a small repo of its own works well), then add
the token as a secret there, for example named SYNC_TOKEN:
gh secret set SYNC_TOKEN -R <you>/<sync-repo>It prompts for the value, so the token doesn't end up in your shell history.
Create .github/workflows/fork-sync.yml in that repository:
name: Fork sync
on:
schedule:
- cron: "*/15 * * * *" # every 15 minutes
workflow_dispatch:
jobs:
sync:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: zuujiscom/green-fork-sync@v1
with:
token: ${{ secrets.SYNC_TOKEN }}
upstream-owner: some-org # owner of the original repos
repos: |
first-repo
second-repoEach name must be the same upstream and in your fork (some-org/first-repo →
<fork-owner>/first-repo). fork-owner defaults to the owner of the repository the
workflow runs in.
To see what it would do before it changes anything, add dry-run: "true" under with:,
then start the workflow by hand:
gh workflow run fork-sync.yml -R <you>/<sync-repo>The run's summary page shows a table with each repo and its result. When it looks right,
remove the dry-run line; the schedule takes over from there.
| input | default | description |
|---|---|---|
token |
(required) | Token that can write to the forks (see Setup). |
upstream-owner |
(required) | User or organization that owns the original repositories. |
fork-owner |
owner of the workflow's repo | User or organization that owns the forks. |
repos |
Repository names, one per line or comma-separated. | |
repos-file |
Path to a file with repository names, one per line (# comments allowed). Needs actions/checkout first. |
|
branch |
main |
Upstream branch to follow. |
fork-branch |
same as branch |
Branch in the fork to move. |
min-age-minutes |
10 |
Skip upstream commits newer than this. |
lookback |
40 |
How many recent upstream commits to consider (max 100). |
ignore-checks |
Check-run and workflow names to leave out of the decision, * wildcards allowed (for example a flaky job, or Dependabot). |
|
require-checks |
Check-run names that must be present and green, same format. | |
ignore-events |
Leave out check runs of workflows started by these events, for example schedule: a nightly job on the branch tip otherwise adds its runs to a commit that was already green on push. |
|
docs-paths |
File patterns whose changes need no CI, * wildcards allowed (for example *.md, .coderabbit.yaml). Commits without checks that only change such files are taken along on top of the green commit. |
|
dry-run |
false |
Only report what would move. |
status-file |
Also write the result table to this Markdown file (commit it yourself if you want it in the repo). |
| output | description |
|---|---|
moved |
Number of forks that were moved. |
failed |
Number of repos that hit an error. The step also fails when this is above 0. |
- Cost: GitHub-hosted runners are free for public repositories. In a private repo each run uses about 1–2 billed minutes, so run it less often (every 2 hours is about 750 minutes a month).
- Scheduled workflows in public repos are disabled after 60 days without repository
activity. If the sync repo itself never changes, re-enable it now and then, or commit
the
status-fileso each sync counts as activity. - Your forks' own CI will run when the action moves their branch, because the push is made with your token. GitHub keeps workflows switched off on new forks until you accept them on each fork's Actions tab.
- Diverged forks (with commits upstream doesn't have) are skipped with a message; sync those yourself.
- Copies that aren't linked forks are supported: the commit is fetched from upstream and pushed without force.
With the GitHub CLI signed in, a dry run reads the APIs and changes nothing:
python3 sync.py --upstream some-org --fork you --dry-run first-repo second-repopython3 sync.py --help lists every option; they match the action inputs.
To work on the action itself, run the offline tests with
python3 -m unittest discover -s tests -v (see CLAUDE.md for the details).