Branch Sync
After a release from main, merge it into develop (or any other branch) automatically, with a push or a pull request, instead of a CI job of your own.
Why
With a git flow (develop for the work, main for the releases), the release commit and its tags are only on main. Until main is merged back into develop:
- the next merge request
develop→mainconflicts on thepackage.jsonandCHANGELOG.mdfiles; - the prereleases of
developare computed from the previous stable version.
sync.rules makes relizy do this back-merge itself, right after the release.
Set It Up
A rule says which branch is merged into which ones:
import { defineConfig } from 'relizy'
export default defineConfig({
sync: {
rules: [{ from: 'main', to: ['develop'] }],
},
})A release from main then merges main into develop. The releases of the other branches sync nothing: a beta from develop or a canary from a feature branch is not merged anywhere. from takes a glob too, for release branches:
export default defineConfig({
sync: {
rules: [
{ from: 'main', to: ['develop'] },
// release/1.x, release/2.x...: back into main and develop, with pull requests
{ from: 'release/*', to: ['main', 'develop'], mode: 'pull-request' },
],
},
})For one run, --sync develop merges into the given branches whatever the rules, --no-sync skips the sync. All the options: Sync Configuration.
What Happens
The sync is a step of relizy release, right after the push of the release commit, before the provider release and the social posts (see the steps). It runs only when the release commit is pushed: never with --no-commit, --no-push or --canary.
For each branch, relizy fetches it, then:
| The branch | relizy | Status |
|---|---|---|
| already has the release | pushes nothing | up-to-date |
| has no commit of its own | moves it to the release commit | fast-forward |
| has its own commits | pushes a merge commit, chore(release): sync {{target}} with {{source}} by default | merged |
| conflicts with the release | pushes nothing, and tells how to merge by hand | conflict |
The merge is computed in memory (git merge-tree): no checkout, no git hook, the working directory of the job is left as it is. It needs git 2.38 or later. If the branch receives commits during the sync, the merge is computed again (3 attempts).
A branch that does not get the release (a conflict, a refused push) does not fail the release, which is already published: the step is marked as failed in the summary, the warning gives the commands, and the release ends with code 0. The report tells it: synced_branches lists the branches that got the release (or their pull request), failed_steps contains sync.
# The commands of a conflict on develop
git fetch origin
git switch develop
git merge origin/main
git push origin developPull Request Mode
When develop is protected and the release cannot push to it, open a pull request instead (a merge request on GitLab):
export default defineConfig({
sync: {
rules: [{ from: 'main', to: ['develop'], mode: 'pull-request' }],
},
})relizy opens one pull request from main into develop per release, or reuses the one already open. When the merge conflicts, the pull request still opens and says on which files: resolve them in it. Merge it with a merge commit, not a squash: a squash merge would leave the release commit and its tags out of develop.
Access
The safety checks check the sync before anything is written: each branch exists on the remote, and the release can push to it (push) or has a token to open the pull requests (pull-request). The rules of a protected branch are only checked by the real push.
| Mode | GitHub Actions | GitLab CI |
|---|---|---|
push | permissions: contents: write, and a branch protection of develop that lets the token push | The job token cannot push by default: a GITLAB_TOKEN (or RELIZY_GITLAB_TOKEN) with the write_repository scope and a role allowed to push to develop. relizy pushes with it, without changing the remote |
pull-request | permissions: pull-requests: write (and "Allow GitHub Actions to create pull requests" in the settings) | A GITLAB_TOKEN with the api scope: the job token cannot open merge requests |
The push to develop can start a pipeline. On GitLab CI, the merge commit and the release commit both start with chore(release):, so the rule that already keeps the release commit from releasing again covers it:
rules:
- if: '$CI_COMMIT_BRANCH == "develop" && $CI_COMMIT_MESSAGE !~ /^chore\(release\): /'On GitHub Actions, a push made with the GITHUB_TOKEN starts no workflow.
Preview and Run It Alone
relizy release --dry-runcomputes the merges without pushing, with the release commit it would create: a branch that already has the released branch showsfast-forwardormerged, as in the real release. A conflict with the commits of the branch shows up before the release, not one on the files the release writes (CHANGELOG.md,package.json): the dry run does not write them.relizy syncsyncs the branches without releasing, e.g. after the access to a branch is fixed, or in a job of its own:relizy sync --to develop. It fails (code1) when a branch does not get the release.
Replace Your Own Job
The usual job of a GitLab pipeline, run after the release job:
sync-develop:
needs: [{job: release, artifacts: true}]
script:
- if [ "$RELIZY_RELEASED" != "true" ]; then exit 0; fi
- git fetch origin main develop
- git checkout -B develop origin/develop
- git merge origin/main --no-edit
- git push origin developbecomes one rule, sync: { rules: [{ from: 'main', to: ['develop'] }] }, with the checks before the release, the push through the GitLab token when the job token cannot push, and a release that is not failed by a conflict.