Repository files navigation

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, whereyou are in the stack, as well as navigate between PRs in a stack.

It is designed to work out of the box withGit Town v12+,but also supports previous versions viamanual configuration.

Please refer to therelease page forthe latest release notes.

Create a workflow file calledgit-town.yml under.github/workflows with the followingcontents:

name:Git Townon:pull_request:branches:      -'**'jobs:git-town:name:Display the branch stackruns-on:ubuntu-latestpermissions:contents:readpull-requests:writesteps:      -uses:actions/checkout@v4      -uses:git-town/action@v1

Once this workflow is committed, the action will visualize your stacked changeswhenever a pull request is created or updated. It also will automatically readyour.git-branches.toml file to determine the main and perennial branches foryour repository.

By default, the action will append the visualization to the bottom of the PR description.If you are using apull request template,you can specify the location of the visualization in the template by adding aHTML commentthat containsbranch-stack inside of it:

##Stack<!-- branch-stack--> 👈 Add this!##Checklist[] Foo[] Bar[] Baz

The action will look for this comment and insert the visualization underneath the commentwhen it runs.

It will also leave behind the comment, so that the next time it runs, it willbe able to use it again to update the visualization:

##Stack-`main`<!-- branch-stack--> 👈 Still there!-\#1:point_left:-\#2##Checklist[] Foo[] Bar[] Baz

The location of the stack visualization can be customized using thelocation input.Valid options for this input include:

• description: This is the default option. The stack visualization will appear within thepull request description. This will require grantingpull-requests: write permissions to theaction.
• comment: The stack visualization will appear in a separate comment. No additional permissionsare required for this option.

-uses:git-town/action@v1with:location:comment

If you don't want the stack visualization to appear on pull requests which arenot partof a stack, addskip-single-stacks: true to the action's inputs.

A pull request is considered to benot a part of a stack if:

• It has no child pull requests.
• It's parent is the main branch or a perennial branch.

-uses:git-town/action@v1with:skip-single-stacks:true

In order to accurately visualize stacked changes, the action needs to fetchall openand closed pull requests. However, this can increase the runtime of the action forlarger/older repositories.

If you're experiencing long runtimes, thehistory-limit input can be configured tolimit the total number of pull requests fetched by the action:

-uses:git-town/action@v1with:history-limit:500# Only fetch the latest 500 pull requests

When creating pull requests from forked repositories, the "Allow edits by maintainers" optionenables contributors to grant/deny maintainers direct push access to the forked branch. Theproblem with this option is that it also overrides the permissions granted to the action'sGITHUB_TOKEN. If edit access is not granted to maintainers, the action will not beable to sync the visualization to the pull request description.

To work around this, you can create aPATwith write access to pull requests, store it as a repository secret, and then passit into the actions'sgithub-token input to grant it sufficient permissions:

steps:    -uses:actions/checkout@v4    -uses:git-town/action@v1with:github-token:${{ secrets.GIT_TOWN_PAT }}# 👈 Add this to `git-town.yml`

If you are using Git Town v11 and below, or are setting up the action for a repositorythat doesn't have a.git-branches.toml, you will need to tell the action what themain branch and perennial branches are for your repository.

The main branch is the default parent branch for new feature branches, and can bespecified using themain-branch input:

-uses:git-town/action@v1with:main-branch:main

The action will default to your repository's default branch, which it fetches viathe GitHub REST API.

Perennial branches are long lived branches and are never shipped.

There are two ways to specify perennial branches: explicitly or via regex. This canbe done with theperennial-branches andperennial-regex inputs respectively:

-uses:git-town/action@v1with:perennial-branches:|      dev      staging      prodperennial-regex:'^release-.*$'

Both inputs can be used at the same time. The action will merge the perennialbranches given into a single, de-duplicated list.

inputs:github-token:required:truedefault:${{ github.token }}main-branch:required:falsedefault:''perennial-branches:required:falsedefault:''perennial-regex:required:falsedefault:''location:required:falsedefault:'description'skip-single-stacks:required:falsedefault:falsehistory-limit:required:falsedefault:'0'

The scripts and documentation in this project are released under theMIT License.