Long Tran
4.4 KiB
Git Town Action V1
This action visualizes your stacked changes when proposing pull requests on GitHub:
This allows you to easily see all related PRs for a given pull request, where you are in the stack, as well as navigate between PRs in a stack.
It is designed to work out of the box with Git Town v12+, but also supports previous versions via manual configuration.
What's New
Please refer to the release page for the latest release notes.
Getting Started
Create the GitHub Actions Workflow File
Create a workflow file called git-town.yml under .github/workflows with the following
contents:
name: Git Town
on:
pull_request:
branches:
- '**'
jobs:
git-town:
name: Display the branch stack
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
- uses: git-town/action@v1
Once this workflow is committed, the action will visualize your stacked changes
whenever a pull request is created or updated. It also will automatically read
your .git-branches.toml file to determine the main and perennial branches for
your repository.
Modify the Pull Request Template
By default, this action will append the visualization to the bottom of the PR description.
If you are using a pull request template,
you can specify the location of the visualization in the template by adding a HTML comment
that contains branch-stack inside of it:
## Stack
<!-- branch-stack -->
## Checklist
[ ] Foo
[ ] Bar
[ ] Baz
This action will look for this comment and insert the visualization underneath the comment when it runs. It will also leave behind the comment, so that the next time it runs, it will be able to use it again to update the visualization:
## Stack
<!-- branch-stack --> 👈 Still there!
- `main`
- \#1 :point_left:
- \#2
## Checklist
[ ] Foo
[ ] Bar
[ ] Baz
Warning
Be careful not to add content between the comment and the visualization, as this action will replace that content each time it updates your PR. Adding content above the tag, or below the list is safe though!
Manual Configuration
If you are using Git Town v11 and below, or are setting up this action for a repository
that doesn't have a .git-branches.toml, you will need to tell this action what the
main branch and perennial branches are for your repository.
Main Branch
The main branch is the default parent branch for new feature branches, and can be
specified using the main-branch input:
- uses: git-town/action@v1
with:
main-branch: 'main'
This action will default to your repository's default branch, which it fetches via the GitHub REST API.
Perennial Branches
Perennial branches are long lived branches and are never shipped.
There are two ways to specify perennial branches: explicitly or via regex. This can
be done with the perennial-branches and perennial-regex inputs respectively:
- uses: git-town/action@v1
with:
perennial-branches: |
dev
staging
prod
perennial-regex: '^release-.*$'
Both inputs can be used at the same time. This action will merge the perennial branches given into a single, de-duplicated list.
License
The scripts and documentation in this project are released under the MIT License.