Repository files navigation

A GitHub App/Action that boosts your GitHub workflow by automating the creationof issue branches (and many more things!)

Unique features offered by this app that are not available on GitHub:

• Configure branch nameformat
• Configure default sourcebranch
• Configure source branch based onlabel
• Automatically open a (draft) PullRequest
• Copy over attributes (such as labels and milestones) from the issue to the(draft)PR
• Configure PR target branch based on issuelabel
• Feature requests are alwayswelcome!

• Installation
• Usage
• Configuration
• Development
• Feedback, suggestions and bug reports
• Contributing
• License

There are two options to run this app as part of your development workflow:

1. Install it as anapp for your organization/account/repository
2. Run it as anaction in your GitHub action YAML configuration

Option 1 is easiest if you're developing on GitHub.com, option 2 gives you fullcontrol how and when the app runs in your development workflow.

The App is free to use for personal, and public organization repositories. Thereisa paid plan on the GitHub Marketplace if you want to use itfor private organization repositories.

You can install the app for your organization/account/repository fromthe GitHubMarketplace

Add this to your workflow YAML configuration:

on:# The issue.opened event below is only needed for the "immediate" mode.# The issue.assigned event below is only needed for the default ("auto") mode.issues:types:[ opened, assigned ]# The issue_comment.created event below is only needed for the ChatOps mode.issue_comment:types:[ created ]# The pull_request events below are only needed for pull-request related features.pull_request:types:[ opened, closed ]jobs:create_issue_branch_job:runs-on:ubuntu-lateststeps:      -name:Create Issue Branchuses:robvanderleek/create-issue-branch@mainenv:GITHUB_TOKEN:${{ secrets.GITHUB_TOKEN }}

The latest GitHub Marketplace release is not always up-to-date (duetothis). To have access toall features please use version@main

The GitHub Action has one output variable:branchName, which contains thename of the branch that was created, or already exists in the repository. Youcan use this output in downstream actions. For a trivial example seethisworkflow.

Uninstall the App by navigating to:Settings > Applications > Installed GitHub Apps > Create Issue Branch > Configure. At the bottom of that page there's abutton to uninstall the Create Issue Branch app.

You can also usethis linkto navigate to the configuration page mentioned above.

This app can support your development workflow in three ways (modes): auto,immediate, and chatops.

In "auto" mode the typical development workflow is:

1. An issue is created, for example: Issue 15: Fix nasty bug!

some time may pass

2. The issue is assigned
3. When the issue is assigned this app will create a new issue branch(for the example issue this branch will be calledissue-15-Fix_nasty_bug)

In "immediate" mode the typical development workflow is:

1. An issue is created, for example: Issue 15: Fix nasty bug!
2. Immediately after creation, this app will create a new issue branch (for theexample issue this branch will be calledissue-15-Fix_nasty_bug)

In "chatops" mode the typical development workflow is:

1. An issue is created, for example: Issue 15: Fix nasty bug!

some time may pass

2. A developer that wants to work on this issue gives the ChatOps command/cib as a comment on the issue
3. This app will create a new issue branch (for the example issue this branchwill be calledissue-15-Fix_nasty_bug) By default the app notifiescreation is completed with a comment on the issue.

GitHub Apps & Actions allow you to define custom and advanced automatedworkflows. Examples of Apps & Actions that can be used alongside this app tocompose tailored issue workflows are:

• project-bot: App for project automation
• github-actions-automate-projects: Action for projectautomation
• auto-card-labeler: Automatically label issues/PRs

To get inspired of what is possible with Actions workflows,seethis configuration.

Remember to always pick the simplest issue workflow that fits your project.

This app does not require a configuration. However, if you want to override thedefault behaviour you can do so by placing a YAML file in your repository atthe location:.github/issue-branch.yml with the overrides.

If the app has a problem with your configuration YAML (e.g.: invalid content)it will create an issue with the title " Error in Create Issue Branch appconfiguration" in the repo. Subsequent runs with an invalid configuration willnot create new issues, only one stays open.

Organization/user wide configuration prevents a configuration in everyindividual repo and is supported by putting the YAML file.github/issue-branch.yml in a repository called.github. So, if yourorganization/username isacme, the full path becomes:https://github.com/acme/.github/blob/main/.github/issue-branch.yml.

Remember to give the GitHub App access to the.github repository, otherwiseit can't load the organization/user wide configuration.

Repository configuration files override the organization/user wideconfiguration file.

The default mode is "auto", meaning a new issue branch is created after anissue is assigned.

You can change the mode to "immediate", meaning a new issue branch is createdimmediately after creating an issue, by putting the following line in yourissue-branch.yml:

mode:immediate

You can change the mode to "chatops", meaning a new issue branch is createdafter commenting on an issue with/create-issue-branch or/cib, by puttingthe following line in yourissue-branch.yml:

mode:chatops

By default the app comments on the issue after creating a branch.

You can change this default behaviour, and make the app silent, by putting the following line inyourissue-branch.yml:

silent:true

Branch names are generated from the issue, there are 3 built-in flavours or it can be customized.

The 3 built-in flavours are:

1. tiny => ani followed by the issue number, for example:i15
2. short => the wordissue followed by the issue number, for example:issue-15
3. full => the word issue followed by the issue number followed by the issue title, forexample:issue-15-Fix_nasty_bug

The default isfull, other types can be configured in the YAML like this:

branchName:tiny

or

branchName:short

To customize branch names you can givebranchName a string value where${...}placeholders are substituted with fields from the GitHub issue or environment variables.

For example, if you would like to have your branch names contain only the issue number and title (similar to the GitLabbranch naming convention), configure it like this:

branchName:'${issue.number}-${issue.title}'

Seetest/fixtures/issues.assigned.json for all possible placeholder names.

Substitution placeholders can also refer to environment variables in GitHub Actions. Environment variable names need tobe prefixed with a% character to distinguish them from GitHub issue fields.

For example, if the environment variableSOME_VAR is defined outside the action it can be used in a branch name likethis:

branchName:'${issue.number}-${%SOME_VAR}-${issue.title}'

Substitution values can be "sliced" with the slice operator:[start, end]. This operator behaves exactly like theJavaScript Stringslice() method.

For example, put this in your configuration YAML to limit issue titles to 64 characters:

branchName:'${issue.number}-${issue.title[0,64]}'

Substitutions for${...} placeholders can be lowercased by putting a, before the closing curly. Likewise,substitutions can be uppercased by putting a^ before the closing curly.

For example, issue titles can be lowercased in branch names like this:

branchName:'${issue.number}-${issue.title,}'

or if you want the complete title in uppercase:

branchName:'${issue.number}-${issue.title^}'

Substitutions can be left padded with zeros using the%n operator, wheren is the minimum number of charactersof the substitution result.

For example, issue numbers can be left padded with zeros like this:

branchName:'issue-${issue.number%4}'

In the example above, if the issue number is 123, the resulting branch name will beissue-0123.

Characters that are not allowed in Git branch names are replaced by default with an underscore (_) character. You canconfigure a different replacement character as follows:

gitSafeReplacementChar:'-'

The above configuration would generate the following branch name for issue 15 that has the title "Fix nastybug":issue-15-Fix-nasty-bug.

Furthermore, you also can replace arbitrary characters in the issue title:

gitReplaceChars:'ab/'

The above configuration replaces all occurences of the characters 'a', 'b' and'/' in the issue title.

This app can automatically link a pull request to the issue for which the issuebranch (of the pull request) was created. You can enable this feature with:

autoLinkIssue:true

Be aware that the app needs to be able to find the issue number in the branchname, otherwise this feature will not work. This feature only works if one ofthe following is true for your app configuration:

• You use the defaultbranchName setting
• YourbranchName setting istiny,short orfull
• Your branch name starts with the issue number
• Your branch name contains the stringissue- (case insensitive) followed bythe issue number, for example:Project-A-Issue-123-Rewrite_in_Clojure

This app can close issues automatically for you when a pull request for anissue branch is merged. You can enable this feature with:

autoCloseIssue:true

Be aware that the app needs to be able to find the issue number in the branchname, otherwise this feature will not work. This feature only works if one ofthe following is true for your app configuration:

• You use the defaultbranchName setting
• YourbranchName setting istiny,short orfull
• Your branch name starts with the issue number
• Your branch name contains the stringissue- (case insensitive) followed bythe issue number, for example:Project-A-Issue-123-Rewrite_in_Clojure

This app can delete issue branches for you when a related issue is closed. Youcan enable this feature with:

autoDeleteBranch:true

Be aware that the app needs to be able to find the issue number in the branchname, otherwise this feature will not work. See also the explanation inthissection.

You can override the source branch (by defaultthe"default branch"of the repository is used) in the configuration like this:

defaultBranch:'dev'

You can override the source branch based on the issue label.

For example, if you want branches for issues with theenhancement label to have thedev branch as a source, andbranches for issues with thebuglabel to have thestaging branch as a source, add this to your configuration YAML:

branches:  -label:enhancementname:dev  -label:bugname:staging

Thelabel field also takes a list of label names. In that case all labels in the list must be matched by labels of theissue. For example:

branches:  -label:      -enhancement      -docsname:docs  -label:enhancementname:dev

In the configuration above issues with the labelsenhancementanddocs will have thedocs branch as a source,while issues with anenhancement labelbut not adocs label will have thedev branch as a source.

When issues have multiple labels the branch of the first match (based on the order in the configuration YAML will beused).

If a configured branch does not exist in the repository thedefault branch is used.

Branch names can be prefixed based on the label of an issue.

For example, if you want branches for issues with theenhancement label to have thefeature/ prefix and branches forissues with thebug label to have thebugfix/ prefix, add this to your configuration YAML:

branches:  -label:enhancementprefix:feature/  -label:bugprefix:bugfix/

You can use${...} placeholders in the prefix to substitute fields from the GitHub issue assignment JSON object. Forexample, if you want the GitHub login name of the user that created the issue in the branch prefix, add this to yourconfiguration YAML:

branches:  -label:enhancementprefix:feature/${issue.user.login}/

Seetest/fixtures/issues.assigned.json for all possible placeholder names.

Runs of this App/Action can be skipped based on the label of an issue.

For example, if you don't want to automatically create branches for issues with thequestion label, add this to your configuration YAML:

branches:  -label:questionskip:true

Wildcard characters '?' (matches any single character) and '*' (matches any sequence of characters, including theempty sequence) can be used in the label field.

For example, to set the default/fallback prefixissues/ for issues that do not have theenhancement orbuglabel, use this configuration:

branches:  -label:enhancementprefix:feature/  -label:bugprefix:bugfix/  -label:'*'prefix:issues/

You can use this default/fallback behaviour also to run the App/Action only for certain issue labels. For example, putthis in your configuration YAML if you want to run the App/Action only for issues with thebug label:

branches:  -label:bugskip:false  -label:'*'skip:true

Remember to put quotes around a single asterisk ('*') in YAML

Automatically open a (draft) Pull Request for the newly created branch. Enable this feature in your configuration YAML,for draft pull requests use:

openDraftPR:true

and for regular pull requests use:

openPR:true

Be aware that draft pull requests are not available in all repositories types, seetheGitHub documentationfor details.

You can override the pull request target branch based on the issue label.

For example, if you want (draft) pull requests for issues with thebug label to have thedevelopment branch as asource and have the pull request target branch set tohotfix, add this to your configuration YAML:

branches:  -label:bugname:developmentprTarget:hotfix

You can skip the creation of branches based on the issue label. This configuration option is typically used togetherwith theopenPR/openDraftPR option to automatically create a (draft)PR between branches.

For example, to automatically open a PR to merge thedevelop branch in therelease branch when the issue has arelease label, add this to your configuration YAML:

openPR:truebranches:  -label:releasename:developprTarget:releaseskipBranch:true

When the App opens a new (draft) Pull Request, it can also copy over thefollowing attributes from your issue:

• Description
• Labels
• Assignee
• Projects (only available in GitHub Action, not in the App)
• Milestone

You can enable this behaviour per attribute in the configuration:

copyIssueDescriptionToPR:truecopyIssueLabelsToPR:truecopyIssueAssigneeToPR:truecopyIssueProjectsToPR:truecopyIssueMilestoneToPR:true

When the App opens a new (draft) Pull Request, it can also copy over a pullrequest template from a file in your repository. The template must be stored ina file named.github/pull_request_template.md.

You can enable this behaviour in the configuration:

copyPullRequestTemplateToPR:true

Automatically opening a (draft) PR for an issue requires an empty commit on the newly created branch (this is arequirement by GitHub). This first empty commit might trigger GitHub Actions CI workflows. You can skip theseworkflows with the following configuration option:

prSkipCI:true

When this option is enabled, aConventionalCommit prefix (including agitmoji) is automatically added to the PR title basedon issue & PR labels.

For example, if there's an issue "Fix nasty bug" and accompanying branchissue-123-Fix-nasty-bug, where either the issue or the PR are labeled as"bug", then whenever a Pull Request for the branch is opened (automatically ormanually) Create Issue Branch will prepend "fix: 🐛" to the Pull Request title,for example "fix: 🐛 isssue 123 Fix nasty bug".

Conventional PR titles create a clear and beautiful Git history. They also makeit possible to implement automatedSemantic Versioningof your software using tools such asSemanticRelease.

By default, for issues/PRs that are labeled with "breaking change" (or"breaking-change") there will be an exclamation mark added to the title, forexample: "feat!: ✨ Change in API".

You can enable conventional Pull Request titles with the followingconfiguration option:

conventionalPrTitles:true

This feature works best if you enable only "Allow squash merging" on yourrepository settings page:

There are three prefix styles you can select: semver (default),semver-no-gitmoji, and gitmoji. You can configure the prefix style with thefollowing configuration option:

conventionalStyle:semver

or:

conventionalStyle:semver-no-gitmoji

or:

conventionalStyle:gitmoji

With the "semantic versioning" (semver) style, Create Issue Branch willprepend "fix: 🐛" to the Pull Request title, for example "fix: 🐛 isssue 123Fix nasty bug"

With thesemver-no-gitmoji style, Create Issue Branch will prepend "fix: " tothe Pull Request title, for example "fix: isssue 123 Fix nasty bug"

With thegitmoji style, Create Issue Branch will prepend "🐛 " to the PullRequest title, for example "🐛 isssue 123 Fix nasty bug"

Prefixes and emoji's for labels can be configured through the optionconventionalLabels. This is the default:

conventionalLabels:fix:bug:'🐛'dependencies:'⬆️'security:'🔒'feat:enhancement:'✨'build:build:'🔧'chore:chore:'♻️'ci:ci:'👷'docs:documentation:'📝'style:style:'💎'refactor:refactor:'♻️'perf:performance:'⚡️'test:test:'✅'breaking:breaking-change:'💥'breaking change:'💥'

For example, to change the emoji for label "bug":

conventionalLabels:fix:bug:'🚑'

Or to add a new label type for features:

conventionalLabels:feat:new-stuff:'🚀'

Or to add a new prefix:

conventionalLabels:my-prefix:my-label:'🏷️'breaking:true

Note: for backwards compatibility,features andfeat will both result in aprefixfeat.

The default message displayed in the issue comments after a branch is created (andsilent mode is not enabled) is:

Branch ${branchName} created!

You can customize this message with thecommentMessage option in the configuration YAML. In the string value for thisoption${branchName} is substituted with the name of the newly created branch and other${...} placeholders aresubstituted with fields from the GitHub issue assignment JSON object.

For example, if you would like to have the original issue title in the comment, confgure it like this:

commentMessage:'Branch ${branchName} created for issue: ${issue.title}'

Seetest/fixtures/issues.assigned.json for all possible placeholder names.

The features below are experimental and may be removed some day or promoted to standard features.

As discussed inthis issue, enabling this featureallows you to give the branch name as an argument to the/cib ChatOps command. For example:/cib Simple NPE fix willcreate a branch namedissue-1-Simple_NPE_fix

experimental:branchNameArgument:true

Unit Tests and coverage are implemented using Jest and Istanbul.

The snippet below shows the script which, upon execution, generates a coverage directory with coverage reports that arethen used by CodeCov to generate a dashboard (description for CodeCov below the snippet)

"coverage":"jest --collect-coverage"

Note: CodeCov is a third-party test coverage tool which can be associated to your GitHub repository to create adashboard based on visual representations of test coverage. CodeCov also tracks improvements in coverage on every pushonce linked. For more information:https://docs.codecov.io/docs

Used CodeCov to generate a coverage dashboard through a bash command run in the prod/dev pipelines.

The bash script can only run if:

• You have a 'codecov' account (just log in with your GitHub account)
• The repository on your GitHub account is linked to your CodeCov account.
• You have a GitHub secret namedCODECOV_SECRET_TOKEN which has the value of the token generated by CodeCov

Please note that once your repository is linked with your CodeCov account you will receive an authentication tokengenerated by CodeCov which you will have to save asCODECOV_SECRET_TOKEN in your GitHub secrets for this repository.The bash script upon execution will provide a link to your CodeCov dashboard on your account.

The snippet below shows the workflow which runs the coverage command through yarn and bash script to generate adashboard on CodeCov.io:

 -run:yarn run coverage -run:bash <(curl -s https://codecov.io/bash) -t ${{secrets.CODECOV_SECRET_TOKEN }}

Please create an issue here:https://github.com/robvanderleek/create-issue-branch/issues

If you like this Action/App, please star ⭐ it.

Create Issue Branch was Built in response to this feature request issue:isaacs/github#1125 (that issue is now closed and thediscussioncontinuoushere andhere)

Early 2022 GitHub added a "Create a branch" buttonto the webUIPerhaps the new GitHub button will be sufficient for your development workflow,if not give this App/Action a try.

The list below contains features that might or might not be implemented in the future. Comment or +1 if this feature isuseful for your use-case.

• Add Projects integration (see issue#142)
• Add issue label management functionality (seeissue#177)
• Choose branch to branch from in ChatOps mode (seeissues#155and#213)

If you have suggestions for how create-issue-branch could be improved, or wantto report a bug,open anissue! All andany contributions are appreciated.

For more, check out theContributing Guide.

ISC © 2019 Rob van der Leekrobvanderleek@gmail.com(https://twitter.com/robvanderleek)