search

kilianpaquier / semantic-release-backmerge

Backmerge feature for semantic-release with automatic PR creation when a conflict is identified. Available for Github, Gitlab, Bitbucket and Gitea
https://www.npmjs.com/package/@kilianpaquier/semantic-release-backmerge
MIT License
2 stars 0 forks source link
backmerge semantic-release-plugin

readme

@kilianpaquier/semantic-release-backmerge

GitHub Actions GitHub Release GitHub Issues GitHub License Coverage

A semantic-release plugin to handle backmerge between branches.

Step Description
verifyConditions Verify the presence of specific plugin configuration alongside required environment variables
success Apply backmerge for the appropriate target branches

How to ?

bun

bun install -D @kilianpaquier/semantic-release-backmerge

npm

npm install -D @kilianpaquier/semantic-release-backmerge

pnpm

pnpm install -D @kilianpaquier/semantic-release-backmerge

yarn

yarn install -D @kilianpaquier/semantic-release-backmerge

How does it work ?

When configured in targets, a provided branch (i.e main) can be backmerged in one or multiple others (i.e. develop) when a released in made with semantic-release.

With the instance of main and develop, develop branch will be check'ed out locally and merged with git merge <branch> --ff -m <commit_message>. It means that if git can avoid a merge commit, it will avoid it.

In the event of conflicts (it may happen, production fixes could be made to main and features developped in develop), a pull request is created from main to develop.

Usage

This plugin can be configured through the semantic-release configuration file.

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/git",
    "@semantic-release/github",
    [
      "@kilianpaquier/semantic-release-backmerge",
      {
        "commit": "chore(release): merge branch ${ from } into ${ to } [skip ci]",
        "targets": [
          { "from": "main", "to": "develop" }
          { "from": "main", "to": "staging" }
          { "from": "staging", "to": "develop" }
        ],
        "title": "Automatic merge failure",
      }
    ],
    "@semantic-release/exec",
  ]
}

Configuration

name required default description
apiPathPrefix Yes Guessed in environment variables. Unless baseUrl is specifically provided. API Prefix for your platform (i.e. /api/v4 for gitlab).
baseUrl Yes Guessed in environment variables Platform base URL (i.e. https://gitlab.com for gitlab).
commit No chore(release): merge branch ${ from } into ${ to } [skip ci] Merge commit in case the fast-forward mode couldn't be done.
dryRun No --dry-run option from semantic-release Whether to really push and create pull requests or only log the actions.
platform Yes Guessed in environment variables. Unless baseUrl is specifically provided. Platform name. Either bitbucket, bitbucket-cloud, gitea, github or gitlab.
targets No [] Backmerge targets, a slice / list of { from: <from>, to: <to> }. from and to can be regexp like (develop\|staging) or v[0-9]+(.[0-9]+)?, etc.
title No Automatic merge failure Pull request title to set when creating pull requests.

Templating

Configuration commit and title are templated with lodash during backmerge or pull request creation. The following data are available:

name type description
from string Backmerge source branch.
to string Backmerge target branch.
lastRelease object Last release with version, gitTag, gitHead, name, and channels fields.
nextRelease object Last release with version, gitTag, gitHead, name, type, channel and notes fields.

Maintenance branches

In some cases, you may want to maintain multiple maintenance branches associated to the same major version.

In that case, semantic-release-backmerge is covering for you. When providing a from branch matching a maintenance branch, then backmerge will only allow backmerge into more recent maintenance branches (of the same major version):

Environment variables

When working with specifics git platforms, and as such sometimes with associated CI functionalities, environment variable are by default provided.

For semantic-release-backmerge to work flawlessly with your platform, you may provide in the next sections the right environment variables.

To avoid painful configurations, you may use the environments variables to automatically guess baseUrl, apiPathPrefix and platform instead of given them in your configuration file.

Bitbucket (data center/server)

variable name description
BITBUCKET_URL Base URL to your bitbucket server
BB_TOKEN Bitbucket token to push backmerged branches or create pull requests
BITBUCKET_TOKEN Bitbucket token to push backmerged branches or create pull requests

Notes:

Bitbucket (cloud)

variable name description
BITBUCKET_CLOUD_URL Base URL to your bitbucket cloud server
BB_TOKEN Bitbucket token to push backmerged branches or create pull requests
BITBUCKET_TOKEN Bitbucket token to push backmerged branches or create pull requests

Notes:

Gitea

variable name description
GITEA_URL Base URL to your gitea server
GITEA_TOKEN Gitea token to push backmerged branches or create pull requests

Notes:

Github

variable name description
GH_URL Base URL to your github server (you must provide it that case apiPathPrefix if it exists on your server)
GITHUB_URL Base URL to your github server (you must provide it that case apiPathPrefix if it exists on your server)
GITHUB_API_URL Base URL to your github server (this variable already exists with github actions)
GH_TOKEN Github token to push backmerged branches or create pull requests
GITHUB_TOKEN Github token to push backmerged branches or create pull requests

Notes:

Gitlab

variable name description
GL_URL Base URL to your gitlab server
GITLAB_URL Base URL to your gitlab server
CI_SERVER_URL Base URL to your gitlab server (this variable already exists with CICD)
GL_TOKEN Gitlab token to push backmerged branches or create pull requests
GITLAB_TOKEN Gitlab token to push backmerged branches or create pull requests

Notes: