{"id":17144992,"url":"https://github.com/kiegroup/git-backporting","last_synced_at":"2025-09-12T21:12:20.486Z","repository":{"id":65040214,"uuid":"573788038","full_name":"kiegroup/git-backporting","owner":"kiegroup","description":"Git backporting is a CLI tool to execute pull request backporting.","archived":false,"fork":false,"pushed_at":"2024-11-03T09:31:13.000Z","size":2487,"stargazers_count":18,"open_issues_count":11,"forks_count":9,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-12-17T03:33:16.064Z","etag":null,"topics":["action","automation","backport","cherry-pick","cli","codeberg","github","github-actions","gitlab","hacktoberfest","merge-requests","pull-requests"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kiegroup.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2022-12-03T12:42:25.000Z","updated_at":"2024-12-15T14:38:12.000Z","dependencies_parsed_at":"2023-12-10T22:23:23.586Z","dependency_job_id":"7c8c04c2-0ac2-42ba-b7d2-43f0a1c82869","html_url":"https://github.com/kiegroup/git-backporting","commit_stats":{"total_commits":106,"total_committers":8,"mean_commits":13.25,"dds":0.4056603773584906,"last_synced_commit":"b9ed3ac959d1479e81bf4f0a5e5f0a72251ce895"},"previous_names":["lampajr/backporting"],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiegroup%2Fgit-backporting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiegroup%2Fgit-backporting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiegroup%2Fgit-backporting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiegroup%2Fgit-backporting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kiegroup","download_url":"https://codeload.github.com/kiegroup/git-backporting/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230438185,"owners_count":18225870,"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":["action","automation","backport","cherry-pick","cli","codeberg","github","github-actions","gitlab","hacktoberfest","merge-requests","pull-requests"],"created_at":"2024-10-14T21:04:02.708Z","updated_at":"2024-12-19T13:08:12.988Z","avatar_url":"https://github.com/kiegroup.png","language":"TypeScript","readme":"\u003ch1 align=\"center\"\u003e\n  Git Backporting \u003c/br\u003e\n  :outbox_tray: :inbox_tray:\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/kiegroup/git-backporting\"\u003e\n    \u003cimg alt=\"ci checks status\" src=\"https://github.com/kiegroup/git-backporting/actions/workflows/ci.yml/badge.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://badge.fury.io/js/@kie%2Fgit-backporting\"\u003e\n    \u003cimg alt=\"npm version\" src=\"https://badge.fury.io/js/@kie%2Fgit-backporting.svg\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n**Git Backporting** is a [NodeJS](https://nodejs.org/) command line tool that provides capabilities to *backport* pull requests (on *GitHub*) and merge requests (on *GitLab*) in an automated way. This tool also comes with a predefined *GitHub* action in order to make CI/CD integration easier for all users.\n\n\nTable of content\n----------------\n\n* **[Who is this tool for](#who-is-this-tool-for)**\n* **[CLI tool](#cli-tool)**\n* **[GitHub action](#github-action)**\n* **[Future works](#future-works)**\n* **[Development](#development)**\n* **[Contributing](#contributing)**\n* **[License](#license)**\n\n## Who is this tool for?\n\n`git-backporting` is a fully configurable tool that provides capabilities to *backport* pull requests (on *GitHub*) and merge requests (on *GitLab*) in an automated way.\n\n\u003e *What is backporting?* - backporting is an action aiming to move a change (usually a commit) from a branch (usually the main one) to another one, which is generally referring to a still maintained release branch. Keeping it simple: it is about to move a specific change or a set of them from one branch to another.\n\nTherefore this tools is for anybody who is working on projects where they have to maintain multiple active branches/versions at the same time. If you are actively cherry-picking many changes from your main branch to other ones, and you mainly do changes through pull requests or merge requests, maybe this tool may be right for you.\n\n## CLI tool\n\n\u003e  All instructions provided below pertain to version `v4` of the tool. If you wish to use an earlier version, please refer to the documentation from the corresponding tag/release.\n\nThis tool is released on the [public npm registry](https://www.npmjs.com/), therefore it can be easily installed using `npm`:\n\n```bash\n$ npm install -g @kie/git-backporting\n```\n\nThen you just have to choose the pull request (or merge request on *Gitlab*) that you would like to backport and the target branch and then simply run the following command:\n\n```bash\n$ git-backporting -tb \u003cbranch\u003e -pr \u003cpull-request-url\u003e -a \u003cgit-token\u003e\n```\n\nA real example could be the following one:\n```bash\n$ git-backporting -tb develop -pr https://github.com/kiegroup/git-backporting-example/pull/47 -a *****\n```\n\nThis is the easiest invocation where you let the tool set / compute most of the backported pull request data. Obviously most of that data can be overridden with appropriate tool options, more details can be found in the [inputs](#inputs) section.\n\n### Requirements\n\n* Node 16 or higher, more details on Node can be found [here](https://nodejs.org/en).\n* Git, see [how to install](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) if you need help.\n\n### How it works?\n\nIt works in this way: given the provided `pull/merge request` it infers the server API to use (either *Github* or *Gitlab* for now) and retrieves the corresponding pull request object (original pull/merge request to be backported into another branch).\n\nAfter that it clones the corresponding git repository, check out in the provided `target branch` and create a new branch from that (name automatically generated if not provided as option).\n\nBy default the tool will try to cherry-pick the single squashed/merged commit into the newly created branch. The `--no-squash` and `--auto-no-squash` options control this behavior according the following table. \n\n| No squash | Auto no squash |Behavior|\n|---|---|---|\n| unset/false | unset/false | cherry-pick a single commit, squashed or merged |\n| set/true | unset/false | cherry-pick all commits found in the the original pull/merge request|\n| (ignored) | set/true | cherry-pick all commits if the original pull/merge request was merged, a single commit if it was squashed |\n\nBased on the original pull request, creates a new one containing the backporting to the target branch. Note that most of these information can be overridden with appropriate CLI options or GHA inputs.\n\n#### cherry-pick strategy\n\nThe default cherry-pick strategy is `recursive` with `theirs` option for automatic conflicts resolution. Therefore, by default, all commits are cherry-picked using the following git-equivalent command:\n```bash\n$ git cherry-pick -m 1 --strategy=recursive --strategy-option=theirs \u003csha\u003e\n```\n\nFrom version `v4.2.0` both can be configured via the `strategy` or `strategy-option` inputs if using the action and the `--strategy` or `--strategy-option` arguments if using the CLI.\n\nThe [default strategy](https://git-scm.com/docs/git-merge#Documentation/git-merge.txt--sltstrategygt) of the `git-cherry-pick` command is different from the defaults of `git-backporting`.\n```bash\n$ git cherry-pick -m 1 \u003csha\u003e\n```\nis the same as:\n```bash\n$ git cherry-pick -m 1 --strategy=ort --strategy-option=find-renames \u003csha\u003e\n```\nIf there is a conflict the backport will fail and require manual intervention.\n\n\u003e **NOTE**: If there are any conflicts, the tool will block the process and exit signalling the failure as there are still no ways to interactively resolve them. In these cases a manual cherry-pick is needed, or alternatively users could manually resume the process in the cloned repository (here the user will have to resolve the conflicts, push the branch and create the pull request - all manually).\n\n### Inputs\n\nThis tool comes with some inputs that allow users to override the default behavior, here the full list of available inputs:\n\n| **Name**      | **Command**          | **Required** | **Description**                                                                                                                                        | **Default** |\n|---------------|----------------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|\n| Version       | -V, --version        | -            | Current version of the tool                                                                                                                            |             |\n| Help          | -h, --help           | -            | Display the help message                                                                                                                               |             |\n| Target Branches | -tb, --target-branch | N            | Comma separated list of branches where the changes must be backported to                                                                                                         |             |\n| Target Branches Pattern | -tbp, --target-branch-pattern | N            | Regular expression pattern to extract target branch(es) from pr labels. The branches will be extracted from the pattern's required `target` named capturing group, e.g., `^backport (?\u003ctarget\u003e([^ ]+))$`                                                                                                         |             |\n| Pull Request  | -pr, --pull-request  | N            | Original pull request url, the one that must be backported, e.g., https://github.com/kiegroup/git-backporting/pull/1                                        |             |\n| Configuration File  | -cf, --config-file  | N            | Configuration file, in JSON format, containing all options to be overridded, note that if provided all other CLI options will be ignored                                        |             |\n| Auth          | -a, --auth           | N            | Git access/authorization token, if provided all token env variables will be ignored. See [auth token](#authorization-token) section for more details | \"\"          |\n| Folder        | -f, --folder         | N            | Local folder full name of the repository that will be checked out, e.g., /tmp/folder                                                                                     | {cwd}/bp    |\n| Git Client       | --git-client        | N            | Git client type \u003cgithub|gitlab|codeberg\u003e, if not set it is infered from pull-request\n| Git User       | -gu, --git-user        | N            | Local git user name                                                       | \"GitHub\"       |\n| Git Email       | -ge, --git-email        | N            | Local git user email                                                       | \"noreply@github.com\"       |\n| Title       | --title        | N            | Backporting pull request title                                                       | \"{original-pr-title}\"       |\n| Body       | --body        | N            | Backporting pull request body                                                           | \"{original-pr-body}\"       |\n| Body Prefix       | --body-prefix        | N            | Prefix to the backporting pull request body                                                          | \"Backport: {original-pr-link}\"       |\n| Reviewers       | --reviewers        | N            | Backporting pull request comma-separated reviewers list                                                           | []       |\n| Assignees       | --assignes        | N            | Backporting pull request comma-separated assignees list                                                           | []       |\n| No Reviewers Inheritance       | --no-inherit-reviewers        | N            | Considered only if reviewers is empty, if true keep reviewers as empty list, otherwise inherit from original pull request                                                           | false       |\n| Backport Branch Names       | --bp-branch-name        | N            | Comma separated lists of the backporting pull request branch names, if they exceeds 250 chars they will be truncated                                                           | bp-{target-branch}-{sha1}...{shaN}       |\n| Labels       | --labels        | N            | Provide custom labels to be added to the backporting pull request                                                           | []       |\n| Inherit labels       | --inherit-labels        | N            | If enabled inherit lables from the original pull request                                                           | false       |\n| No squash       | --no-squash        | N            | Backport all commits found in the pull request. The default behavior is to only backport the first commit that was merged in the base branch. | |\n| Auto no squash  | --auto-no-squash   | N            | If the pull request was merged or is open, backport all commits. If the pull request commits were squashed, backport the squashed commit. | |\n| Strategy       | --strategy        | N            | Cherry pick merging strategy, see [git-merge](https://git-scm.com/docs/git-merge#_merge_strategies) doc for all possible values                                                           | \"recursive\"       |\n| Strategy Option       | --strategy-option        | N            | Cherry pick merging strategy option, see [git-merge](https://git-scm.com/docs/git-merge#_merge_strategies) doc for all possible values                                                           | \"theirs\"       |\n| Cherry-pick Options       | --cherry-pick-options        | N            | Additional cherry-pick options, see [git-cherry-pick](https://git-scm.com/docs/git-cherry-pick) doc for all possible values                                                           | \"theirs\"       |\n| Additional comments       | --comments        | N            | Semicolon separated list of additional comments to be posted to the backported pull request                                                           | []       |\n| Enable error notification       | --enable-err-notification        | N            | If true, enable the error notification as comment on the original pull request                                                           | false       |\n| Dry Run       | -d, --dry-run        | N            | If enabled the tool does not push nor create anything remotely, use this to skip PR creation                                                           | false       |\n\n\u003e **NOTE**: `pull request` and (`target branch` or `target branch pattern`) are *mandatory*, they must be provided as CLI options or as part of the configuration file (if used).\n\n#### Authorization token\n\nSince version `4.5.0` we introduced a new feature that allows user to provide the git access token through environment variables. These env variables are taken into consideration only if the `--auth/-a` is not provided as argument/input.\nHere the supported list of env variables:\n- `GITHUB_TOKEN`: this is checked only if backporting on Github platform.\n- `GITLAB_TOKEN`: this is checked only if backporting on Gitlab platform.\n- `CODEBERG_TOKEN`: this is checked only if backporting on Codeberg platform.\n- `GIT_TOKEN`: this is considered if none of the previous envs are set.\n\n\u003e **NOTE**: if `--auth` argument is provided, all env variables will be ignored even if not empty.\n\n#### Configuration file example\n\nThis is an example of a configuration file that can be used.\n```json\n{\n  \"pullRequest\": \"https://gitlab.com/\u003cnamespace\u003e/\u003crepo\u003e/-/merge_requests/1\",\n  \"targetBranch\": \"old\",\n  \"folder\": \"/tmp/my-folder\",\n  \"title\": \"Override Title\",\n  \"auth\": \"*****\"\n}\n```\nKeep in mind that its structure MUST match the [Args](src/service/args/args.types.ts) interface, which is actually a camel-case version of the CLI options.\n\n### Supported git services\n\nRight now **Git Backporting** supports the following git management services:\n * ***GITHUB***: Introduced since the first release of this tool (version `1.0.0`). The interaction with this system is performed using [*octokit*](https://octokit.github.io/rest.js) client library.\n\n * ***GITLAB***: This has been introduced since version `3.0.0`, it works for both public and private *GitLab* servers. The interaction with this service is performed using plain [*axios*](https://axios-http.com) requests. The *gitlab* api version that is used to make requests is `v4`, at the moment there is no possibility to override it.\n\n * ***CODEBERG***: Introduced since version `4.4.0`, it works for public [codeberg.org](https://codeberg.org/) platform. Thanks to the api compatibility with GitHub, the interaction with this service is performed using using [*octokit*](https://octokit.github.io/rest.js) client library.\n\n\u003e **NOTE**: by default, all gitlab requests are performed setting `rejectUnauthorized=false`, planning to make this configurable too.\n\n## GitHub action\n\nThis action can be used in any *GitHub* workflow, below you can find a simple example of manually triggered workflow backporting a specific pull request (provided as input).\n\n```yml\nname: Pull Request Backporting using Git Backporting\n\non: \n  workflow_dispatch:\n    inputs:\n      targetBranch:\n        description: 'Target branch'\n        required: true\n        type: string\n      pullRequest:\n        description: 'Pull request'\n        required: true \n        type: string\n      dryRun:\n        description: 'Dry run'\n        required: false\n        default: \"true\" \n        type: string\n\njobs:\n  backporting:\n    name: \"Backporting\"\n    runs-on: ubuntu-latest\n    steps:\n      - name: Backporting\n        uses: kiegroup/git-backporting@main\n        with:\n          target-branch: ${{ inputs.targetBranch }}\n          pull-request: ${{ inputs.pullRequest }}\n          auth: ${{ secrets.GITHUB_TOKEN }}\n          dry-run: ${{ inputs.dryRun }}\n```\n\nYou can also use this action with other events - you'll just need to specify `target-branch` and `pull-request` params.\n\nFor example, this configuration creates a pull request against branch `v1` once the current one is merged, provided that the label `backport-v1` is applied:\n\n```yaml\nname: Pull Request Backporting using Git Backporting\n\non:\n  pull_request_target:\n    types:\n      - closed\n      - labeled\n\nenv:\n  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n\njobs:\n  backporting:\n    name: \"Backporting\"\n    # Only react to merged PRs for security reasons.\n    # See https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target.\n    if: \u003e\n      github.event.pull_request.merged\n      \u0026\u0026 (\n        github.event.action == 'closed'\n          \u0026\u0026 contains(github.event.pull_request.labels.*.name, 'backport-v1')\n        || (\n          github.event.action == 'labeled'\n          \u0026\u0026 contains(github.event.label.name, 'backport-v1')\n        )\n      )\n    runs-on: ubuntu-latest\n    steps:\n      - name: Backporting\n        uses: kiegroup/git-backporting@main\n        with:\n          target-branch: v1\n          pull-request: ${{ github.event.pull_request.url }}\n```\n\nFor a complete description of all inputs see [Inputs section](#inputs).\n\n## Future works\n\n**Git Backporting** is still in development mode, this means that there are still many future works and extension that can be implemented. I'll try to summarize the most important ones:\n\n- Provide a way to backport single commit (or a set of them) if no original pull request is present.\n- Integrate this tool with other git management services (like Bitbucket) to make it as generic as possible.\n- Integrate it into other CI/CD services like gitlab CI.\n- Provide some reusable *GitHub* workflows.\n\n## Development\n\n### Package release\n\nThe release of this package is entirely based on [release-it](https://github.com/release-it/release-it) tool. I created some useful scripts that can make the release itself quite easy.\n\n\n#### Automatic release\n\nThe first step is to prepare the changes for the next release, this is done by running:\n\n```bash\n$ npm run release:prepare:all\n```\n\n\u003e NOTE: running locally this requires `npm login`, please consider using `.github/workflows/prepare-release.yml` if you don't have permission on the npm package.\n\nThis script performs the following steps:\n 1. Automatically computes the next version based on the last commits\n 2. Create a new branch `release/v${computed_version}`\n 3. Apply all changes, like version and changelog upgrade\n 4. Commit those changes: `chore: release v${compute_version}`\n\nAfter that you should just push the new branch and open the pull request.\n\u003e NOTE: if you don't want to run this preparation from you local environment, there is already a workflow that does all these steps, including the pull request. See [Prepare release](.github/workflows/prepare-release.yml) workflow.\n\nOnce the release preparion pull request got merged, you can run [Release package](.github/workflows/release.yml) workflow that automatically performs the release itself, including npm publishing, git tag and github release.\n\n#### Manual release\n\nIn case we would like to perform a manual release, it would be enough to open a pull request changing the following items:\n- Package version inside the `package.json`\n- Provide exhaustive changelog information inside `CHANGELOG.md`\n- Commit like `chore: release v\u003cversion\u003e`\n\nOnce the release preparion pull request got merged, run [Release package](.github/workflows/release.yml) workflow.\n\n## Contributing\n\nThis is an open source project, and you are more than welcome to contribute :heart:!\n\nEvery change must be submitted through a *GitHub* pull request (PR). Backporting uses continuous integration (CI). The CI runs checks against your branch after you submit the PR to ensure that your PR doesn’t introduce errors. If the CI identifies a potential problem, our friendly PR maintainers will help you resolve it.\n\n\u003e **Note**: this project follows [git-conventional-commits](https://gist.github.com/qoomon/5dfcdf8eec66a051ecd85625518cfd13) standards, thanks to the [commit-msg hook](./.husky/commit-msg) you are not allowed to use commits that do not follow those standards.\n\n1. Fork it (https://github.com/kiegroup/git-backporting).\n\n2. Create your feature branch: (git checkout -b feature).\n\n3. Commit your changes with a comment: (git commit -am 'Add some feature').\n\n4. Push to the branch to GitHub: (git push origin feature).\n\n5. Create a new pull request against `main` branch.\n\n\u003e **Note**: you don't need to take care about typescript compilation and minifycation, there are automated [git hooks](./.husky) taking care of that!\n\n**Hint**: if you are still in a `work in progress` branch and you want to push your changes remotely, consider adding `--no-verify` for both `commit` and `push`, e.g., `git push origin \u003cfeat-branch\u003e --no-verify`\n\n## License\n\nGit backporting open source project is licensed under the [MIT](./LICENSE) license.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiegroup%2Fgit-backporting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiegroup%2Fgit-backporting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiegroup%2Fgit-backporting/lists"}