git-town / action Goto Github PK

View Code? Open in Web Editor NEW

3.0 2.0 2.0 490 KB

Visualizes your stacked changes when proposing pull requests on GitHub

Home Page: https://www.git-town.com

License: MIT License

JavaScript 7.38% TypeScript 92.62%

action's Introduction

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.

action's People

Contributors

Stargazers

Watchers

Forkers

stoopkidddd mattd-tg

action's Issues

False error when PR is merged before action runs

Error that occurs:

/home/runner/work/_actions/git-town/action/v1/dist/index.js:23416
          throw new NotFoundGraphError("Graph.".concat(method, ': could not find the "').concat(nodeOrEdge, '" node in the graph.'));
                ^

NotFoundGraphError2: Graph.setNodeAttribute: could not find the "<pr_head_ref>" node in the graph.

The simplest fix would be to check whether or not the current PR is merged before running the main action.

Standardised method for executing CI checks on local machine

There isn't a standardised method for executing CI checks (e.g. tests, linters, etc) from the local machine for this project yet. Setting this up will allow contributors to get faster & more immediate feedback on potential issues with their PRs, which will help reduce friction to the overall contribution process.

Action fails on when PR's base ref exists as a branch but not a PR

Given this branch stack, with no PRs created for any branch:

main
- parent-branch
  - child-branch

If a PR is created for child-branch, the action will fail be because parent-branch does not have an associated PR. This happens because the action uses the repo's pull requests when building up the stack graph. To fix this, we should first add all branches in the repository as nodes on the graph, even if they don't appear in PRs, so that leafs can be properly connected when iterating through the pull requests.

Is also related to #34, as we will need to handle pagination to make sure that we have a full list of branches for the repository. This doesn't scale very well for large repositories (e.g. monorepos), but it's better than the action failing and not producing a branch stack at all.

Investigate how other tools display single-branch stacks

Accept GitHub Marketplace Developer Agreement

@kevgo We need to accept the GitHub Marketplace Developer Agreement before being able to publish this action onto the marketplace. Would you be able to help out with that? 🙏

I believe you can accept the agreement by going to "Releases" > "Draft a release", then clicking on "GitHub Marketplace Developer Agreement" (which is greyed out for me here):

Comment on PR instead of modifying the PR's description

It would be great if this action could post a comment (and keep that one up to date) instead of modifying the PR description.

Action fails on branches that have a perennial branch as a parent

Skip adding comment on solo PR's

Going to take a stab at making a PR for this, but wanted to put an issue up first.

It would be nice if there was a config option to tell the github action not to add a stack to the description if the PR isn't actually part of a stack, but just a solo PR pointing to the trunk by itself with no children

There are other people on my team not stacking their PR's, and having the comment added to their solo PRs is very confusing and does not lend to an opt-in approach.

Config option proposal - skipSinglePR: boolean added in config.ts -> configSchema

Log context & debugging information before action run

Debugging edge cases has been quite challenging due to the lack of logging performed by the action. We should log context & additional debugging information during the run of the action. This will also aid bug reporting in the future as the logs could form part of a bug report.

Unable to create releases - must accept GitHub Developer Marketplace Agreement first

@kevgo It appears that we need to accept the GitHub Developer Marketplace Agreement again, any chance you could help out with this? The agreement must have changed -- IIRC we've accepted this in the past 🤷‍♂️

Don't add ref to node graph if it already exists

Adding a ref (e.g. main) to the branch graph will cause a runtime error:

Run git-town/action@v1
/home/runner/work/_actions/git-town/action/v1/dist/index.js:2[4](https://github.com/connecX/monorepo/actions/runs/8963195676/job/24613133789?pr=557#step:3:5)845
        throw new UsageGraphError('Graph.addNode: the "'.concat(node2, '" node already exist in the graph.'));
              ^

UsageGraphError2: Graph.addNode: the "main" node already exist in the graph.
    at _addNode (/home/runner/work/_actions/git-town/action/v1/dist/index.js:2484[5](https://github.com/connecX/monorepo/actions/runs/8963195676/job/24613133789?pr=557#step:3:6):15)
    at MultiDirectedGraph3.addNode (/home/runner/work/_actions/git-town/action/v1/dist/index.js:25574:24)
    at /home/runner/work/_actions/git-town/action/v1/dist/index.js:42854:15
    at Array.forEach (<anonymous>)
    at main (/home/runner/work/_actions/git-town/action/v1/dist/index.js:42853:1[6](https://github.com/connecX/monorepo/actions/runs/8963195676/job/24613133789?pr=557#step:3:7))
    at run (/home/runner/work/_actions/git-town/action/v1/dist/index.js:46955:10)
    at process.processTicksAndRejections (node:internal/process/task_queues:[9](https://github.com/connecX/monorepo/actions/runs/8963195676/job/24613133789?pr=557#step:3:10)5:5)

We should check whether the ref exists as a node in the graph first before adding it.

Remote branches not fetched with pagination

This leads to errors building the stack graph when using explicit/regex'd perennial branches. The solution here is to use Octokit's pagination client instead of the REST client to fetch remote branches.