Merge Preview
Before merging a pull request or a merge request, see what its merge releases - versions, tags, dist-tag, what the pull request brings - and fail the check when the release of the merge would fail.
How It Works
relizy merge-preview runs in the pipeline of a pull request (GitHub) or a merge request (GitLab), with the options of the job that releases after the merge. It computes the release of the merge, as relizy release will run it on the target branch, and writes nothing: no version, no changelog, no commit, no tag, no push, no publish, no hook.
It then:
- comments the pull request with what the merge releases, updated at each push (see The Comment);
- with
mergePreview.check, sets the commit statusrelizy/merge-previewon the last commit of the pull request: green with the versions, red when the release of the merge would fail (see What Fails the Check). Off by default: the job itself fails; - writes the comment in the summary of the CI job, and prints the preview in the terminal: a box per version group with its packages, the problems, the commits not following the commit convention and the warnings;
- exits with an error when the release of the merge would fail.
Relizy does not guess which pipeline releases: the CI says it, by running the preview with the release type and the options of its release job. A preview of the release job relizy release --minor --config web --yes is relizy merge-preview --minor --config web.
Set It Up
relizy init offers the merge preview (yes by default, and with --yes). In a project already set up, relizy merge-preview init only adds its workflow.
GitHub Actions
The relizy action with command: merge-preview, on the pull requests into the branch that releases:
name: Merge preview
on:
pull_request:
branches: [main]
# edited: a new title (the commit of a squash merge) or a new base
types: [opened, synchronize, reopened, edited]
concurrency:
group: merge-preview-${{ github.event.pull_request.number }}
cancel-in-progress: true
jobs:
merge-preview:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
issues: write
statuses: write
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
- uses: relizy/action@v2
with:
command: merge-preview
# The release-type and the profile of the release job, and its options that change the release, e.g.:
# profile: beta
# args: --config webThe default checkout of a pull request is its merge commit with the target branch: the preview is computed on it.
GitLab CI
The merge-preview component of the CI/CD catalog, next to the release one. It runs in the merge request pipelines into the default branch:
include:
- component: gitlab.com/relizy/relizy/release@2
- component: gitlab.com/relizy/relizy/merge-preview@2
inputs:
# The release-type and the profile of the release job, and its options that change the release, e.g.:
profile: beta
args: --config webGive the merge preview the profile of the release job (profile input of the action and of the component, --profile of the CLI, relizy 2.3.0 or later): it previews the versions and the dist-tag of that profile, and a canary profile previews a canary version (canary: true in the report).
The comment needs GITLAB_TOKEN (an access token with the api scope): the CI_JOB_TOKEN of the job cannot comment. When the merge request is behind its target branch (a pipeline that is not a merged results one), the target branch is merged into the clone of the job before the preview.
Any CI
Run relizy merge-preview, with the options of the release job, in the pipeline of the pull request. Relizy reads the pull request from the variables of GitHub Actions (GITHUB_BASE_REF, the event of the run) and GitLab CI (CI_MERGE_REQUEST_*). Elsewhere, and on a local run, it previews the next release of the current branch in the terminal, without comment nor commit status:
relizy merge-previewHow the Merge Is Computed
The preview is the real release of the merge: the commits of the target branch not released yet, plus the ones of the pull request. Each released package tells what the pull request brings to it (this PR: 1 feature) and what comes from the target branch (main: 1 fix).
A squash merge turns the commits of the pull request into one commit, whose message decides the bump: a pull request of fix: commits titled feat!: new API releases a major. mergePreview.squash tells whether the merge squashes. By default (auto), Relizy asks the provider:
- GitHub: the method of the auto-merge when it is enabled, else the merge methods allowed by the repository (only squash, or no squash). The commit follows the settings of the repository: its title is the title of the pull request, or the message of its only commit (
COMMIT_OR_PR_TITLE, the default), and its body holds the messages of the commits (COMMIT_MESSAGES, the default: aBREAKING CHANGE:of a commit stays one), the description or nothing; - GitLab: the squash option of the project, else the one of the merge request. The commit is the title of the merge request.
When only the merge will tell (several methods allowed), the preview computes both, and shows both when they release different versions.
What Fails the Check
The check fails, and the job exits with an error, only when the release of the merge would fail, or release a broken result. A major bump or a merge that releases nothing are normal outcomes: they never fail it.
- A version already published: the new version of a package is already on its registry, the publish would fail. The registry is checked with the token of the job; when it cannot tell (a private registry without token), the preview only warns.
- A tag already taken: a tag of the release already exists on the remote, the push would fail.
- A squash commit that is not a Conventional Commit: the release would ignore the changes of the pull request. Write its title as
type(scope): subject. - An error: an invalid config, or a bump that cannot be computed.
A squash title that is not a Conventional Commit fails the check only when the merge squashes for sure: the repository only allows squash merges, or the auto-merge squashes. When the merge method is left open, they are warnings of the comment: a merge commit or a rebase does not have them. A project that never squashes sets mergePreview.squash to false, or turns the squash merges off in the settings of the repository.
To block the merge of a pull request whose release would fail:
- GitHub: require the check of the merge preview job in the protection of the branch or in a ruleset (Settings > Branches, or Settings > Rules), or the status
relizy/merge-previewwithmergePreview.check; - GitLab: turn on Pipelines must succeed (Settings > Merge requests > Merge checks). The failed job of the merge preview fails the pipeline, so it blocks the merge.
Commits Not Following the Commit Convention
The commits of the pull request, and its squash commit, are linted with relizy commitlint when mergePreview.commitlint is true, or auto and the project uses it: a commitlint option in its config, or a commit-msg hook running relizy commitlint (husky, lefthook, simple-git-hooks, the hooks of git). It is off by default: a commitlint job fails on them, before the merge.
The commits failing it are only warnings, in their own section of the comment and of the terminal: they never fail the check nor the job, and the history is often too late to reword. relizy release does not lint the commits: a commit such as feat: 3.1.0 breaks the convention of the project (its subject is too short), but it is a Conventional Commit, released as a feature. As relizy commitlint, the preview follows the merge method:
- the squash commit starts with If you squash merge when the merge method is left open;
- the commits a squash merge drops, when it squashes for sure, are folded apart (1 commit not kept by the squash merge);
- the squash commit is not linted with
commitlint.title: 'off', nor when it takes the message of the only commit of a GitHub pull request (the commit is linted).
--commitlint and --no-commitlint override it for a run.
The Comment
The comment has its own hidden marker, <!-- relizy-merge-preview -->: it is updated in place at each run (with prComment.mode: 'recreate', posted again at the bottom of the pull request and the previous one deleted), apart from the comments of the releases of the pull request (canary, prerelease). After the merge, the release of the merge rewrites it with what was released: the prediction becomes the result.
### 🔮 If you merge this pull request
relizy releases **2 packages** from `main`, published with the dist-tag `latest`:
**maz-ui** `5.2.0` → `5.3.0` (tag `v5.3.0`)
| Package | Version | Why |
| ----------- | ----------------- | ------------------ |
| maz-ui | `5.2.0` → `5.3.0` | this PR: 1 feature |
| @maz-ui/mcp | `5.2.0` → `5.3.0` | `main`: 1 fix |
<sub>Computed on `main@abc1234` + this pull request `@def5678` · commits kept: the repository does not allow squash merges · by relizy</sub>The footer tells the commit of the target branch the preview was computed on: the preview runs at each push of the pull request, not when the target branch moves on. The release of the merge always computes the versions again.
Tokens and Permissions
The comment and the commit status use the token of the provider releases (tokens.github or tokens.gitlab, see Tokens):
- GitHub: the
GITHUB_TOKENof the job, withpull-requests: writeandissues: write(the comment) andstatuses: write(the status, withmergePreview.check). The pull requests opened from a fork get a read-only token: the preview is printed in the summary of the job, without comment nor status. - GitLab: a project or personal access token with the
apiscope, inGITLAB_TOKEN. - Registry: none for public packages on npmjs.com, checked without token. Restricted packages and private registries need the registry token (
NPM_TOKEN) to tell whether a version is published;relizy initadds it then. Without it, the preview only warns.
--no-comment turns the comment off, --check turns the status on (or mergePreview.comment and mergePreview.check).
Limits
- There is no preview of a canary: it publishes right away, from the commit of the pull request.
- A project whose relizy does not know
merge-previewfails with an unknown command: update relizy.