{"id":13527441,"url":"https://github.com/saitho/semantic-release-backmerge","last_synced_at":"2025-04-01T09:31:33.680Z","repository":{"id":43756834,"uuid":"236156799","full_name":"saitho/semantic-release-backmerge","owner":"saitho","description":":twisted_rightwards_arrows: semantic-release plugin to back-merge a release into a develop branch","archived":false,"fork":false,"pushed_at":"2024-09-04T07:13:26.000Z","size":868,"stargazers_count":60,"open_issues_count":15,"forks_count":11,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-28T16:57:05.010Z","etag":null,"topics":["back-merge","backmerge","develop","git","git-flow","gitflow","gitops","hacktoberfest","semantic-release"],"latest_commit_sha":null,"homepage":"https://saitho.github.io/semantic-release-backmerge/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/saitho.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-25T10:43:45.000Z","updated_at":"2025-02-02T16:25:14.000Z","dependencies_parsed_at":"2024-01-13T22:54:09.155Z","dependency_job_id":"a0be4e39-2986-4a25-874d-8f4998105d42","html_url":"https://github.com/saitho/semantic-release-backmerge","commit_stats":{"total_commits":119,"total_committers":9,"mean_commits":"13.222222222222221","dds":0.3529411764705882,"last_synced_commit":"fb3d5afc29e7cfcc016a9dbb3a692c07b1100c7e"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saitho%2Fsemantic-release-backmerge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saitho%2Fsemantic-release-backmerge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saitho%2Fsemantic-release-backmerge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saitho%2Fsemantic-release-backmerge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/saitho","download_url":"https://codeload.github.com/saitho/semantic-release-backmerge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246616140,"owners_count":20806064,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["back-merge","backmerge","develop","git","git-flow","gitflow","gitops","hacktoberfest","semantic-release"],"created_at":"2024-08-01T06:01:48.050Z","updated_at":"2025-04-01T09:31:33.198Z","avatar_url":"https://github.com/saitho.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# @saithodev/semantic-release-backmerge\n\n[**semantic-release**](https://github.com/semantic-release/semantic-release) plugin to back-merge a release in the project's [git](https://git-scm.com/) repository.\n\n**Note:** semantic-release in its core is not intended to be used with Git Flow where a stable (`master`/`main`) branch and a unstable branch (`develop`/`next`) exist. This plugin enables to use semantic-release with such branches, however it does NOT guarantee using semantic-release with Git Flow.\n\nEspecially automatic hotfix releases may not be possible as those usually lead to merge conflicts with develop that have to be resolved manually.\nIn such cases the release workflow will fail, causing a red pipeline!\n\n[![Build Status](https://travis-ci.com/saitho/semantic-release-backmerge.svg?branch=master)](https://travis-ci.com/saitho/semantic-release-backmerge)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=semantic-release-backmerge\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=semantic-release-backmerge)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n\n| Step               | Description                                                                                                |\n|--------------------|------------------------------------------------------------------------------------------------------------|\n| `verifyConditions` | Verify the access to the remote Git repository, the ['backmergeBranches'](#backmergeBranches) option configuration. |\n| `done`             | Create a back-merge into the configured branch if the release is successful.                               |\n\n## Install\n\n```bash\n$ npm install @saithodev/semantic-release-backmerge -D\n```\n\n## Usage\n\nThe plugin can be configured in the [**semantic-release** configuration file](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration):\n\n**Note:** As this plugin will rebase your \"develop\" branch onto your \"master\" branch, you may not have any unstaged files in your workspace.\nIf you do, you may set the [clearWorkspace](#clearWorkspace) option to stash them and restore them with [restoreWorkspace](#restoreWorkspace) if needed.\n\n```json\n{\n  \"plugins\": [\n    \"@semantic-release/commit-analyzer\",\n    \"@semantic-release/release-notes-generator\",\n    [\n      \"@saithodev/semantic-release-backmerge\",\n      {\n        \"backmergeBranches\": [\"dev\"],\n        \"plugins\": [\n          [\n            \"@semantic-release/exec\",\n            {\n              \"successCmd\": \"echo 'Version in master is ${nextRelease.version}' \u003e test.txt \u0026\u0026 git add test.txt\"\n            }\n          ]\n        ]\n      }\n    ]\n  ]\n}\n```\n\n### Jenkins\n\nIf you're using Jenkins, you may need to set the username and password for Git as below (see [#12](https://github.com/saitho/semantic-release-backmerge/issues/12)):\n\n```jenkinsfile\nwithCredentials([usernamePassword(credentialsId: JENKINS_GIT_CREDENTIALS_ID, passwordVariable: 'GIT_PASSWORD', usernameVariable: 'GIT_USERNAME')]) {\n    sh(\"git config credential.username ${GIT_USERNAME}\")\n    sh(\"git config credential.helper '!f() { echo password=$GIT_PASSWORD; }; f'\")\n}\nwithCredentials([usernameColonPassword(credentialsId: JENKINS_GIT_CREDENTIALS_ID, variable: 'GIT_CREDENTIALS')]) {\n    nodejs(JENKINS_NODE_JS_INSTALLATION_LABEL) {\n        sh(\"npx semantic-release\")\n    }\n}\n```\n\n### Backmerging into protected branches\n\nYou can backmerge into protected branches if repository admins/owners are allowed to do that.\nMake sure to provide an admin/owner's access token or credentials (e.g. via `GITHUB_TOKEN`).\n\n**For GitHub Actions** you also need to disable `persist-credentials` in the checkout action:\n```yaml\n- uses: actions/checkout@v2\n  with:\n    persist-credentials: false\n```\nThe personal access token in `GITHUB_TOKEN` needs access to the `repo` scope.\n\n## Configuration\n\n### Options\n\n| Options   | Description                                                                     | Default   |\n|-----------|---------------------------------------------------------------------------------|-----------|\n| `backmergeBranches` | The branches where the release is merged into. See [backmergeBranches](#backmergeBranches).  | ['develop']   |\n| `backmergeStrategy` | How to perform the backmerge. See [backmergeStrategy](#backmergeStrategy).  | rebase   |\n| `plugins` | Plugins defined here may stage files to be included in a back-merge commit. See [plugins](#plugins).   |  []  |\n| `message` | The message for the back-merge commit (if files were changed by plugins. See [message](#message).   | `chore(release): Preparations for next release [skip ci]`     |\n| `forcePush` | If set the back-merge will be force-pushed. See [forcePush](#forcePush).   | false |\n| `clearWorkspace` | Whether to stash the current workspace before backmerge. See [clearWorkspace](#clearWorkspace).   | false |\n| `restoreWorkspace` | Restore the stashed workspace after backmerge completed. See [restoreWorkspace](#restoreWorkspace).   | false |\n| `mergeMode` | Mode for merging (when `backmergeStrategy=merge`). See [mergeMode](#mergeMode).   | none |\n| `fastForwardMode` | Fast forwarding option for merging (when `backmergeStrategy=merge`). See [fastForwardMode](#fastForwardMode).   | none |\n\n#### `backmergeBranches`\n\nBranch names that should receive the back-merge. If none is given, the default value is used.\nThis argument takes a list of branch name strings or objects. A branch object looks like this:\n`{from: \"master\", to: \"dev\"}`\nIn this example, a release from `master` branch is merged into `dev` branch. With that you can perform conditional backmerges,\ni.e. backmerges that only occur when merged from a certain branch.\n\nHere is an example where all releases will backmerge into `develop` and releases from `next` branch will be backmerged into `staging` as well.\n\n```json\n{\n  \"plugins\": [\n    \"@semantic-release/commit-analyzer\",\n    \"@semantic-release/release-notes-generator\",\n    [\n      \"@saithodev/semantic-release-backmerge\",\n      {\n        \"backmergeBranches\": [\"develop\", {\"from\": \"next\", \"to\": \"staging\"}]\n      }\n    ]\n  ]\n}\n```\n\nYou may use [Lodash template](https://lodash.com/docs#template) variables in branch name strings. The following variables are available:\n\n| Parameter           | Description                                                                                                                             |\n|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------|\n| `branch`            | The branch from which the release is done.                                                                                              |\n| `branch.name`       | The branch name.                                                                                                                        |\n| `branch.type`       | The [type of branch](https://github.com/semantic-release/semantic-release/blob/beta/docs/usage/workflow-configuration.md#branch-types). |\n| `branch.channel`    | The distribution channel on which to publish releases from this branch.                                                                 |\n| `branch.range`      | The range of [semantic versions](https://semver.org) to support on this branch.                                                         |\n| `branch.prerelease` | The prerelease detonation to append to [semantic versions](https://semver.org) released from this branch.                              |\n\n#### `plugins`\n\nUse this if you have to make changes to the files for your development branch (e.g. setting a -dev version).\nIt uses the same plugin structure as semantic-release, but only trigger the \"success\" step after rebase from develop onto master is done and just before it is pushed.\n\n*Note:* Please make sure that the files you changed are staged to Git workspace. Only then they will be committed.\n\n#### `message`\n\nThe message for the back-merge commit is generated with [Lodash template](https://lodash.com/docs#template). The following variables are available:\n\n| Parameter           | Description                                                                                                                            |\n|---------------------|----------------------------------------------------------------------------------------------------------------------------------------|\n| `branch`            | The branch from which the release is done.                                                                                             |\n| `branch.name`       | The branch name.                                                                                                                       |\n| `branch.type`       | The [type of branch](https://github.com/semantic-release/semantic-release/blob/beta/docs/usage/workflow-configuration.md#branch-types). |\n| `branch.channel`    | The distribution channel on which to publish releases from this branch.                                                                |\n| `branch.range`      | The range of [semantic versions](https://semver.org) to support on this branch.                                                        |\n| `branch.prerelease` | The prerelease detonation to append to [semantic versions](https://semver.org) released from this branch.                              |\n| `lastRelease`       | `Object` with `version`, `gitTag` and `gitHead` of the last release.                                                                   |\n| `nextRelease`       | `Object` with `version`, `gitTag`, `gitHead` and `notes` of the release being done.                                                    |\n\n#### `allowSameBranchMerge`\n\nIf you want to be able to back-merge into the same branch as the branch that was being released from, enable this setting.\n\n**Note**: It is recommended to include `[skip ci]` in the commit message to not trigger a new build. Some CI service support the `[skip ci]` keyword only in the subject of the message.\n\n#### `forcePush`\n\nSetting this option will force-push the commits from back-merge onto the develop branch.\n\n**Warning:** This will override commits that are not in the develop branch, so make sure that really is what you want!\n\n#### `clearWorkspace`\n\nSetting this option will stash all uncommitted changes from Git workspace before attempting rebase.\n\n#### `restoreWorkspace`\n\nSetting this option will restore the stashed changes after the backmerge completed.\n\n#### `backmergeStrategy`\n\nThis setting will determine whether the _develop_ branch should be rebased onto _master_ or _master_ should be merged into _develop_.\nAllowed values: rebase (default), merge\n\n#### `mergeMode`\n\nThis setting will be used to determine how merge conflicts are resolved when using the `merge` backmerge strategy.\n\nAllowed values: none (default), ours, theirs\n\nnone = no merge conflict resolve (process will abort on merge conflicts!)\n\nours = apply changes from _develop_ branch\n\ntheirs = apply changes from _master_ branch\n\n#### `fastForwardMode`\n\nThis setting will be used to determine the fast forwarding strategy when using the `merge` backmerge strategy.\n\nAllowed values: none (default), ff, no-ff, ff-only\n\nnone = default setting which is the same as ff.\n\nff = when possible resolve the merge as a fast-forward (only update the branch pointer to match the merged branch; do not create a merge commit). When not possible (when the merged-in history is not a descendant of the current history), create a merge commit.\n\nno-ff = create a merge commit in all cases, even when the merge could instead be resolved as a fast-forward.\n\nff-only = resolve the merge as a fast-forward when possible. When not possible, refuse to merge and exit with a non-zero status.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaitho%2Fsemantic-release-backmerge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaitho%2Fsemantic-release-backmerge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaitho%2Fsemantic-release-backmerge/lists"}