Skip to content

mergePreview() ​

Preview from code what the merge of the pull request of the CI job releases, and know whether its release would fail.

Signature ​

ts
function mergePreview(options?: MergePreviewOptions): Promise<ReleaseReport>

Options: MergePreviewOptions, the options of the release job that change the release (type, preid, tag, publish, configName, groups...), the outputs of the preview (comment, check), commitlint: true to lint the commits, and changelog: true for the changelog entries of the release.

Behavior ​

  • Computes the release of the merge as release() will run it on the target branch, and writes nothing: no version, changelog, commit, tag, push, publish nor hook. See Merge Preview.
  • In the pipeline of a pull request, comments it (unless comment: false) and, with check: true ('auto': on GitHub only), sets the commit status relizy/merge-preview: off by default. Without comment nor check, the preview is only computed: nothing is posted (outside a pull request pipeline, nothing is posted either). The report is still written as release.report says: in GitHub Actions, the outputs and the summary of the job (release.report.github: false turns them off).
  • Resolves the ReleaseReport of the preview: released: false, dryRun: true, status released when the merge releases a package, nothing otherwise, the versions and tags by version group (release), and mergePreview:
    • pullRequest, the number of the pull request (kept for the reports of relizy 2), and pullRequestDetails, the pull request itself: provider, kind, number (the same), title, targetBranch, merged. None outside a pull request pipeline
    • branch, the squash mode (squash), packages (each released package: versions, reason, commits, from the pull request or not), squashPackages when a squash merge would release other versions
    • problems, commitlint (the commits failing the commitlint of the project: warnings, they never reject; merge tells whether the merge keeps each of them: kept, squash with a squash merge only, dropped by the squash merge), warnings, publish (enabled, distTag), changelogs (with changelog: true), posted (comment, status), and the markdown of the comment
  • Its steps are the merge-preview step of the progress events (onProgress): one step:start/step:done pair per part of the preview (the merge, the release, the checks, the comment, the commit status).
  • Rejects with a MergePreviewError when the release of the merge would fail (a version or a tag already taken, a squash commit that is not a Conventional Commit, an error of the config): its message lists the problems, and its report is the report of the preview.

Example ​

ts
import { mergePreview, MergePreviewError } from 'relizy'

try {
  const report = await mergePreview({ tag: 'next', comment: false })
  console.log(report.mergePreview?.markdown)
}
catch (error) {
  if (error instanceof MergePreviewError) {
    console.error(error.message)
  }
  throw error
}

Only computed, for an application showing it:

ts
import { mergePreview, MergePreviewError } from 'relizy'

const report = await mergePreview({ comment: false, check: false, changelog: true })
  .catch((error: unknown) => {
    // The release would fail: the report lists the problems
    if (error instanceof MergePreviewError && error.report) {
      return error.report
    }
    throw error
  })

for (const pkg of report.mergePreview?.packages ?? []) {
  console.log(pkg.name, pkg.oldVersion, '->', pkg.newVersion, pkg.reason)
}

See Also ​