Merge Branches Managed on Issue

Merge Branches Managed on Issue is a tool to merge listed branches on an issue into the specified branch. I intend this tool would be used to manage a "staging" branch among many team members. Consider the case the "staging" environment of your application exists in a single place, and many members want to test their changes on the same "staging" environment at the same time. The deployment for the staging is usually based on a single Git commit/branch/tag, so the team members have to merge their changes into a single branch. In this case, they have to carefully manage their branches and describe what branches are deployed to the "staging" environment like this:

branch	author	PR	note
feature/add-special-button	@yykamei	#122	This will be tested until September 3.
refactor-top-page	@octocat	#132

This tool will automatically parse such a managed table on a GitHub issue and merge branches carefully.

Usage

Create a GitHub issue and write its body like this:

## staging

| branch      | author   | PR  | note |
| ----------- | -------- | --- | ---- |
| add-button  | @yykamei | #78 |      |
| add-special | @yykamei | #79 |      |

## production-ready

| branch     | author   | PR  | note |
| ---------- | -------- | --- | ---- |
| add-button | @yykamei | #78 |      |

The heading of the markdown means the name of "base branch", which will include merge commits from listed in the markdown table. In this case, add-button and add-special will be merged into staging, and add-button will be merged into production-ready.

Important

The markdown table must have branch in its headers.

After creating an issue, configure this tool with the following workflow:

name: Merge Branches Managed on Issue
concurrency: merge_branches # This might be required to prevent multiple jobs from running at the same time
on:
  workflow_dispatch:
    inputs:
      base-branch:
        description: base-branch
        required: true
      force:
        description: force
        required: false
        default: "false"
  delete:
  issues:
    types: [opened, edited, reopened]
  issue_comment:
    types: [created, edited]

jobs:
  merge:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: yykamei/merge-branches-managed-on-issue@main
        with:
          issue-number: 1234 # <== This is the previously created issue's number

If you want to avoid predictable conflicts, put your scripts in before-merge and/or after-merge. This is an example of these parameters. This case considers YOUR-PRIVATE-GEM will be always conflicted among developers, so it first changes Gemfile and Gemfile.lock to the same state before merging, and then it makes the merged branch (staging) refer to its namesake of YOUR-PRIVATE-GEM.

name: Merge Branches Managed on Issue
on:
  workflow_dispatch:
    inputs:
      base-branch:
        description: base-branch
        required: true
      force:
        description: force
        required: false
        default: "false"

jobs:
  merge:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: 3

      - uses: yykamei/merge-branches-managed-on-issue@main
        with:
          issue-number: 1
          shell: bash -exuo pipefail
          before-merge: |
            sed -i -e "s#^gem.*YOUR-PRIVATE-GEM.*\$#gem 'YOUR-PRIVATE-GEM', github: 'your-org/YOUR-PRIVATE-GEM', branch: 'main'#" Gemfile
            bundle lock --update YOUR-PRIVATE-GEM --conservative
            git add Gemfile Gemfile.lock
            if [[ $(git diff --cached | wc -l) == 0 ]]; then
              exit 0
            fi
            git commit --message="Change the version of YOUR-PRIVATE-GEM to refer to the main" --no-edit
          after-merge: |
            sed -i -e "s#^gem.*YOUR-PRIVATE-GEM.*\$#gem 'YOUR-PRIVATE-GEM', github: 'your-org/YOUR-PRIVATE-GEM', branch: 'staging'#" Gemfile
            bundle lock --update YOUR-PRIVATE-GEM --conservative
            git add Gemfile Gemfile.lock
            if [[ $(git diff --cached | wc -l) == 0 ]]; then
              exit 0
            fi
            git commit --message="Change the version of YOUR-PRIVATE-GEM to refer to staging" --no-edit

After configuring the workflow, go to the GitHub Actions page and select the workflow name, which is "Merge Branches Managed on Issue" in this example, and trigger the workflow with the branch name.

You should get the merged branch! That's it 🚀

Action inputs

These are all available inputs.

Name	Description	Required	Default
issue-number	The GitHub issue number in which the branches are listed	true	-
path	Relative path under $GITHUB_WORKSPACE to place the repository	false	.
shell	The shell command to invoke a specified source code. This is typically used for before-merge option. The default is bash -eo pipefail on Linux. Currently, the Windows platform is not supported. Note this value will be just splitted by whitespaces	false	bash -eo pipefail
before-merge	Script that will be run before merging through the shell option. This will be invoked after checking out to each target and the base branch, so you can modify commits for each branch. This is useful to avoid possible merge conflicts	false	""
after-merge	Script that will be run after merging through the shell option. This will be invoked after checking out to each target and the base branch, so you can modify commits for each branch	false	""
inputs-param-base-branch	The name for a base branch in the workflow_dispatch action	false	base-branch
inputs-param-force	The name for force option in the workflow_dispatch action	false	force
modified-branch-suffix	The suffix for the modified branch. If you don't set before-merge or after-merge, the modified branch and the original branch will be the same	false	.modified
command-prefix	The comment prefix to trigger some actions.	false	/mbmi
token	The GitHub token used to create an authenticated client	false	GITHUB_TOKEN

Append or remove a branch through comments

You can append or remove a branch to/from the markdown table through pull request comments. For example, you're opening a pull request #431 whose head branch is add/special-feature, and your GitHub account name is octocat. At this point, you can append your branch by just posting a comment on the pull request like this:

/mbmi append-to staging

And then, the branch add/special-feature will be appended to the markdown table, and you can get the following result:

## staging

| branch              | author   | PR   | note |
| ------------------- | -------- | ---- | ---- |
| add-button          | @yykamei | #78  |      |
| add-special         | @yykamei | #79  |      |
| add/special-feature | @octocat | #431 |      |

Also, you can remove your working branch like this:

/mbmi remove-from staging

FAQ

What should I do when some of branches listed change?

TBD

What should I do when some of branches listed are deleted?

TBD

Contributing

Please take a look at the CONTRIBUTING.md. It's always a pleasure to receive any contributions 😄