A light-weight lint workflow when using GitHub along with PivotalTracker for project management. Works well when used alongside pivotal-flow.
To make pivotal-lint
a part of your workflow, just add a pivotal-lint.yml
file in your .github/workflows/
directory in your GitHub repository.
name: pivotal-lint
on: [pull_request]
jobs:
pivotal-lint:
runs-on: ubuntu-latest
steps:
- uses: cleartax/pivotal-lint@master
name: pivotal-lint
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
pivotal-token: ${{ secrets.PIVOTAL_TOKEN }}
skip-branches: '^(production-release|master|release\/v\d+)$'
skip-comments: true
pr-threshold: 1000
It can also be used as part of an existing workflow by adding it as a step. More information about the options here.
If you want more stability in versions of pivotal-lint
than @master
you can also use the semantic releases for pivotal-lint.
Example:
# ...
steps:
- uses: cleartax/pivotal-lint@v2.3.0
name: pivotal-lint
# ...
pivotal-lint
adds a status check which helps you avoid merging PRs which are missing a valid story ID in the branch name. It will use the PivotalTracker API to validate a given story id.
When a PR passes the above check, pivotal-lint
will also add the story details to the top of the PR description. It will pick details such as the story title, type, points and labels and add them to the PR description.
pivotal-lint
will automatically label PRs with:
- A team name label based on the PivotalTracker Project name (the project the story belongs to). For example, if your project name is
Escher POD
then it will addescher
as a label. HOTFIX-PROD
- if the PR is raised againstproduction-release
.HOTFIX-PRE-PROD
- if the PR is raised againstrelease/v*
.- Pivotal story type (feature, chore, bug).
pivotal-lint
will add comments to a PR to encourage better PR practices:
A good PR title
When the title of the PR matches the title of the story well.When the title of the PR is slightly different compared to the title of the story
When the title of the PR is very different compared to the title of the story
A comment discouraging PRs which are too large (based on number of lines of code changed).
Batman says no large PRs π¦key | description | required | default |
---|---|---|---|
github-token |
Token used to update PR description. GITHUB_TOKEN is already available when you use GitHub actions, so all that is required is to pass it as a param here. |
true | null |
pivotal-token |
API Token used to fetch Pivotal Story information. Must have read access to your PivotalTracker projects. Check here on how to get a Pivotal API Token | true | null |
skip-branches |
A regex to ignore running pivotal-lint on certain branches, like production etc. |
false | ' ' |
skip-comments |
A Boolean if set to true pivotal-lint will skip adding lint comments for PR title. |
false | false |
pr-threshold |
An Integer based on which pivotal-lint will add a comment discouraging huge PRs. |
false | 800 |
Since tokens are private, we suggest adding them as GitHub secrets.
Since GitHub actions take string inputs, skip-branches
must be a regex which will work for all sets of branches you want to ignore. This is useful for merging protected/default branches into other branches. Check out some examples in the tests.
pivotal-lint
already skips PRs which are filed by bots (for eg. dependabot). You can add more bots to this list, or add the branch-format followed by the bot PRs to the skip-branches
option.
Follow the instructions here to know more about GitHub actions.
Why is a PivotalTracker ID required in the branch names?
PivotalTracker ID is required in order to:
- Automate change-logs and release notes βοΈ.
- Automate alerts to QA/Product teams and other external stake-holders π.
- Help us retrospect the sprint progress π.
Is there a way to get around this?
Nope πAre there any tools to automate this?
Yes, check out pivotal-flow π