|
1 | 1 | # action-semantic-pull-request |
2 | 2 |
|
3 | | -This is a GitHub Action that ensures your PR title matches the [Conventional Commits spec](https://www.conventionalcommits.org/). The typical use case is to use this in combination with a tool like [semantic-release](https://github.com/semantic-release/semantic-release) to automate releases. |
| 3 | +This is a GitHub Action that ensures that your pull request titles match the [Conventional Commits spec](https://www.conventionalcommits.org/). Typically, this is used in combination with a tool like [semantic-release](https://github.com/semantic-release/semantic-release) to automate releases. |
4 | 4 |
|
5 | 5 | Used by: [Apache](https://github.com/apache/pulsar) · [Vercel](https://github.com/vercel/ncc) · [Microsoft](https://github.com/microsoft/SynapseML) · [Firebase](https://github.com/firebase/flutterfire) · [AWS](https://github.com/aws-ia/terraform-aws-eks-blueprints) · [Electron](https://github.com/electron/forge) – and [many more](https://github.com/amannn/action-semantic-pull-request/network/dependents). |
6 | 6 |
|
7 | 7 | ## Examples |
8 | 8 |
|
9 | | -**Valid PR titles:** |
| 9 | +**Valid pull request titles:** |
10 | 10 | - fix: Correct typo |
11 | 11 | - feat: Add support for Node.js 18 |
12 | 12 | - refactor!: Drop support for Node.js 12 |
13 | 13 | - feat(ui): Add `Button` component |
14 | 14 |
|
15 | | -> Note that since PR titles only have a single line, you have to use `!` to indicate breaking changes. |
| 15 | +> Note that since pull request titles only have a single line, you have to use `!` to indicate breaking changes. |
16 | 16 |
|
17 | 17 | See [Conventional Commits](https://www.conventionalcommits.org/) for more examples. |
18 | 18 |
|
|
30 | 30 | - edited |
31 | 31 | - synchronize |
32 | 32 |
|
| 33 | +permissions: |
| 34 | + pull-requests: read |
| 35 | + |
33 | 36 | jobs: |
34 | 37 | main: |
35 | 38 | name: Validate PR title |
|
40 | 43 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} |
41 | 44 | ``` |
42 | 45 |
|
| 46 | +See the [event triggers documentation](#event-triggers) below to learn more about what `pull_request_target` means. |
| 47 | + |
43 | 48 | ## Configuration |
44 | 49 |
|
45 | 50 | The action works without configuration, however you can provide options for customization. |
@@ -102,15 +107,55 @@ feat(ui): Add `Button` component |
102 | 107 | # See: https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#headerpattern |
103 | 108 | headerPattern: '^(\w*)(?:\(([\w$.\-*/ ]*)\))?: (.*)$' |
104 | 109 | headerPatternCorrespondence: type, scope, subject |
105 | | - # For work-in-progress PRs you can typically use draft pull requests |
106 | | - # from GitHub. However, private repositories on the free plan don't have |
107 | | - # this option and therefore this action allows you to opt-in to using the |
108 | | - # special "[WIP]" prefix to indicate this state. This will avoid the |
109 | | - # validation of the PR title and the pull request checks remain pending. |
110 | | - # Note that a second check will be reported if this is enabled. |
| 110 | +``` |
| 111 | +
|
| 112 | +### Work-in-progress pull requests |
| 113 | +
|
| 114 | +For work-in-progress PRs you can typically use [draft pull requests from GitHub](https://github.blog/2019-02-14-introducing-draft-pull-requests/). However, private repositories on the free plan don't have this option and therefore this action allows you to opt-in to using the special "[WIP]" prefix to indicate this state. |
| 115 | +
|
| 116 | +**Example:** |
| 117 | +
|
| 118 | +``` |
| 119 | +[WIP] feat: Add support for Node.js 18 |
| 120 | +``` |
| 121 | +
|
| 122 | +This will prevent the PR title from being validated, and pull request checks will remain pending. |
| 123 | +
|
| 124 | +**Attention**: If you want to use the this feature, you need to grant the `pull-requests: write` permission to the GitHub Action. This is because the action will update the status of the PR to remain in a pending state while `[WIP]` is present in the PR title. |
| 125 | + |
| 126 | +```yml |
| 127 | +name: "Lint PR" |
| 128 | +
|
| 129 | +permissions: |
| 130 | + pull-requests: write |
| 131 | +
|
| 132 | +jobs: |
| 133 | + main: |
| 134 | + name: Validate PR title |
| 135 | + runs-on: ubuntu-latest |
| 136 | + steps: |
| 137 | + - uses: amannn/action-semantic-pull-request@v5 |
| 138 | + env: |
| 139 | + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} |
| 140 | + with: |
111 | 141 | wip: true |
112 | 142 | ``` |
113 | 143 |
|
| 144 | +### Legacy configuration for validating single commits |
| 145 | + |
| 146 | +When using "Squash and merge" on a PR with only one commit, GitHub will suggest using that commit message instead of the PR title for the merge commit. As it's easy to commit this by mistake this action supports two configuration options to provide additional validation for this case. |
| 147 | + |
| 148 | +```yml |
| 149 | + # If the PR only contains a single commit, the action will validate that |
| 150 | + # it matches the configured pattern. |
| 151 | + validateSingleCommit: true |
| 152 | + # Related to `validateSingleCommit` you can opt-in to validate that the PR |
| 153 | + # title matches a single commit to avoid confusion. |
| 154 | + validateSingleCommitMatchesPrTitle: true |
| 155 | +``` |
| 156 | +
|
| 157 | +However, [GitHub has introduced an option to streamline this behaviour](https://github.blog/changelog/2022-05-11-default-to-pr-titles-for-squash-merge-commit-messages/), so using that instead should be preferred. |
| 158 | +
|
114 | 159 | ## Event triggers |
115 | 160 |
|
116 | 161 | There are two events that can be used as triggers for this action, each with different characteristics: |
|
137 | 182 | - edited |
138 | 183 | - synchronize |
139 | 184 |
|
| 185 | +permissions: |
| 186 | + pull-requests: read |
| 187 | +
|
140 | 188 | jobs: |
141 | 189 | main: |
142 | 190 | name: Validate PR title |
@@ -174,15 +222,3 @@ jobs: |
174 | 222 |
|
175 | 223 | </details> |
176 | 224 |
|
177 | | -## Legacy configuration |
178 | | -
|
179 | | -When using "Squash and merge" on a PR with only one commit, GitHub will suggest using that commit message instead of the PR title for the merge commit and it's easy to commit this by mistake. To help out in this situation this action supports two configuration options. However, [GitHub has introduced an option to streamline this behaviour](https://github.blog/changelog/2022-05-11-default-to-pr-titles-for-squash-merge-commit-messages/), so using that instead should be preferred. |
180 | | -
|
181 | | -```yml |
182 | | - # If the PR only contains a single commit, the action will validate that |
183 | | - # it matches the configured pattern. |
184 | | - validateSingleCommit: true |
185 | | - # Related to `validateSingleCommit` you can opt-in to validate that the PR |
186 | | - # title matches a single commit to avoid confusion. |
187 | | - validateSingleCommitMatchesPrTitle: true |
188 | | -``` |
|
0 commit comments