{"id":20447108,"url":"https://github.com/git-town/action","last_synced_at":"2025-09-12T00:37:52.829Z","repository":{"id":226001823,"uuid":"762402254","full_name":"git-town/action","owner":"git-town","description":"Visualizes your stacked changes when proposing pull requests on GitHub","archived":false,"fork":false,"pushed_at":"2025-07-13T09:54:38.000Z","size":253,"stargazers_count":24,"open_issues_count":6,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-09-06T22:03:39.081Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.git-town.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/git-town.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-02-23T17:50:13.000Z","updated_at":"2025-08-11T23:16:36.000Z","dependencies_parsed_at":"2024-07-18T02:43:20.881Z","dependency_job_id":"066bdc19-482f-43d5-881e-6a934ec9e1c4","html_url":"https://github.com/git-town/action","commit_stats":null,"previous_names":["git-town/action"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/git-town/action","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-town%2Faction","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-town%2Faction/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-town%2Faction/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-town%2Faction/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/git-town","download_url":"https://codeload.github.com/git-town/action/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-town%2Faction/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274732451,"owners_count":25339345,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-11T02:00:13.660Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-15T10:24:37.884Z","updated_at":"2025-09-12T00:37:52.818Z","avatar_url":"https://github.com/git-town.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/git-town/git-town/main/website/src/logo.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/git-town/git-town/main/website/src/logo-dark.svg\"\u003e\n    \u003cimg alt=\"Git Town logo\" src=\"https://raw.githubusercontent.com/git-town/git-town/main/website/src/logo.svg\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n# Git Town Action v1\n\nThis action visualizes your stacked changes when proposing pull requests on GitHub:\n\n![](./docs/example-visualization.png)\n\nThis allows you to easily see all related PRs for a given pull request, where\nyou are in the stack, as well as navigate between PRs in a stack.\n\nIt is designed to work out of the box with [Git Town](https://github.com/git-town/git-town) v12+,\nbut also supports previous versions via [manual configuration](#manual-configuration).\n\n## What's New\n\nPlease refer to the [release page](https://github.com/git-town/action/releases/latest) for\nthe latest release notes.\n\n## Getting Started\n\n### Create the GitHub Actions Workflow File\n\nCreate a workflow file called `git-town.yml` under `.github/workflows` with the following\ncontents:\n\n```yaml\nname: Git Town\n\non:\n  pull_request:\n    branches:\n      - '**'\n\njobs:\n  git-town:\n    name: Display the branch stack\n    runs-on: ubuntu-latest\n\n    permissions:\n      contents: read\n      pull-requests: write\n\n    steps:\n      - uses: actions/checkout@v4\n      - uses: git-town/action@v1\n```\n\nOnce this workflow is committed, the action will visualize your stacked changes\nwhenever a pull request is created or updated. It also will automatically read\nyour `.git-branches.toml` file to determine the main and perennial branches for\nyour repository.\n\n### Modify the Pull Request Template\n\nBy default, the action will append the visualization to the bottom of the PR description.\nIf you are using a [pull request template](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository),\nyou can specify the location of the visualization in the template by adding a [HTML comment](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#hiding-content-with-comments)\nthat contains `branch-stack` inside of it:\n\n```md\n## Stack\n\n\u003c!-- branch-stack --\u003e 👈 Add this!\n\n## Checklist\n\n[ ] Foo\n[ ] Bar\n[ ] Baz\n```\n\nThe action will look for this comment and insert the visualization underneath the comment\nwhen it runs.\n\nIt will also leave behind the comment, so that the next time it runs, it will\nbe able to use it again to update the visualization:\n\n```md\n## Stack\n\n- `main` \u003c!-- branch-stack --\u003e 👈 Still there!\n  - \\#1 :point_left:\n    - \\#2\n\n## Checklist\n\n[ ] Foo\n[ ] Bar\n[ ] Baz\n```\n\n## Customization\n\n### Visualization Location\n\nThe location of the stack visualization can be customized using the `location` input.\nValid options for this input include:\n\n- `description`: This is the default option. The stack visualization will appear within the\n  pull request description. This will require granting `pull-requests: write` permissions to the\n  action.\n- `comment`: The stack visualization will appear in a separate comment. No additional permissions\n  are required for this option.\n\n```yaml\n- uses: git-town/action@v1\n  with:\n    location: comment\n```\n\n### Skip Single Stacks\n\nIf you don't want the stack visualization to appear on pull requests which are **not** part\nof a stack, add `skip-single-stacks: true` to the action's inputs.\n\nA pull request is considered to be **not** a part of a stack if:\n- It has no child pull requests.\n- It's parent is the main branch or a perennial branch.\n\n```yaml\n- uses: git-town/action@v1\n  with:\n    skip-single-stacks: true\n```\n\n### History Limit\n\nIn order to accurately visualize stacked changes, the action needs to fetch _all_ open\nand closed pull requests. However, this can increase the runtime of the action for\nlarger/older repositories.\n\nIf you're experiencing long runtimes, the `history-limit` input can be configured to\nlimit the total number of pull requests fetched by the action:\n\n```yaml\n- uses: git-town/action@v1\n  with:\n    history-limit: 500 # Only fetch the latest 500 pull requests\n```\n\n\u003e [!WARNING]\n\u003e You may encounter inaccuracies in the visualization when customizing `history-limit` as\n\u003e open pull requests may refer to closed pull requests not fetched within the configured\n\u003e limits.\n\n## Common Issues\n\n### Visualization missing on pull requests from forked repositories\n\nWhen creating pull requests from forked repositories, the \"Allow edits by maintainers\" option\nenables contributors to grant/deny maintainers direct push access to the forked branch. The\nproblem with this option is that it also overrides the permissions granted to the action's\n`GITHUB_TOKEN`. If edit access is not granted to maintainers, the action will not be\nable to sync the visualization to the pull request description.\n\nTo work around this, you can create a [PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)\nwith write access to pull requests, store it as a repository secret, and then pass\nit into the actions's `github-token` input to grant it sufficient permissions:\n\n```yaml\n  steps:\n    - uses: actions/checkout@v4\n    - uses: git-town/action@v1\n      with:\n        github-token: ${{ secrets.GIT_TOWN_PAT }} # 👈 Add this to `git-town.yml`\n```\n\n## Manual Configuration\n\nIf you are using Git Town v11 and below, or are setting up the action for a repository\nthat doesn't have a `.git-branches.toml`, you will need to tell the action what the\nmain branch and perennial branches are for your repository.\n\n### Main Branch\n\nThe main branch is the default parent branch for new feature branches, and can be\nspecified using the `main-branch` input:\n\n```yaml\n- uses: git-town/action@v1\n  with:\n    main-branch: main\n```\n\nThe action will default to your repository's default branch, which it fetches via\nthe GitHub REST API.\n\n### Perennial Branches\n\nPerennial branches are long lived branches and are never shipped.\n\nThere are two ways to specify perennial branches: explicitly or via regex. This can\nbe done with the `perennial-branches` and `perennial-regex` inputs respectively:\n\n```yaml\n- uses: git-town/action@v1\n  with:\n    perennial-branches: |\n      dev\n      staging\n      prod\n    perennial-regex: '^release-.*$'\n```\n\nBoth inputs can be used at the same time. The action will merge the perennial\nbranches given into a single, de-duplicated list.\n\n## Reference\n\n```yaml\ninputs:\n  github-token:\n    required: true\n    default: ${{ github.token }}\n  main-branch:\n    required: false\n    default: ''\n  perennial-branches:\n    required: false\n    default: ''\n  perennial-regex:\n    required: false\n    default: ''\n  location:\n    required: false\n    default: 'description'\n  skip-single-stacks:\n    required: false\n    default: false\n  history-limit:\n    required: false\n    default: '0'\n```\n\n## License\n\nThe scripts and documentation in this project are released under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-town%2Faction","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgit-town%2Faction","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-town%2Faction/lists"}