Sign-off was created to help make sure that QA has a chance to test PRs before they have been merged. This is accomplished by using a label to block the PR from being merged. Once the PR has been approved by QA, the label will be removed and the PR will be cleared for being merged into your main branch. Sign-off also has a manual override switch just in case the necessary party is out of the office.
For this to work, you'll need to decide on a label to add to each PR. The default label needed for blocking the PR is needs-qa, but that can be changed once you add the workflow to your repo (this is covered in the input parameters section). Unfortunately needs-qa does not come as one of the default labels for your repository (you can find that list here). Creating a label for your repo is easy and instructions can be found here.
Side note: To make sure that you are always adding the necessary label to the PR, I recommend that you use Labeler. You can specify what label you want to automatically add to a PR each time one is created. This will eliminate human error by not manually adding the label yourself.
It is highly recommended that the action be run when a PR has a label removed or when a PR review has been submitted. You are free to use it with other event triggers as well, but these are the two that will give the best results.
on:
pull_request:
types: [unlabeled]
pull_request_review:
types: [submitted]You'll need to add a new yaml file to the <project-root>/.github/workflow directory. You can name the file anything you like (ex. sign-off.yml).
You can copy and paste the template below into your file and this will give you the bare minimum for using the action:
name: Check for Sign Off
on:
pull_request:
types: [unlabeled]
pull_request_review:
types: [submitted]
jobs:
sign-off-check:
name: Check sign-off
runs-on: ubuntu-latest
steps:
- name: sign off
uses: krogerco/sign-off@v1.1.1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}You can customize the setup of sign-off to your liking. This can be done by editing the following list of input parameters:
| Parameter | Required | Description |
|---|---|---|
| github-token | YES | The value needed is ${{ secrets.GITHUB_TOKEN }} (as seen above). |
| branch-name | NO | This is the branch that has the user list you want to use. The default value is main. |
| file-name | NO | This is the name of the json file you want to use. Do not add the file extension. The default value is sign-off. |
| label | NO | This is the label that needs to be removed from the PR for the merge to take place. The default value is needs-qa. |
Here is an example of the yaml file with all of the inputs filled in:
name: Check for Sign Off
on:
pull_request:
types: [unlabeled]
pull_request_review:
types: [submitted]
jobs:
sign-off-check:
name: Check sign-off
runs-on: ubuntu-latest
steps:
- name: sign off
uses: krogerco/sign-off@v1.1.1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
branch-name: 'main'
file-name: 'sign-off'
label: 'needs-qa'This is the list of users that need to give their approval for the PR to be merged. The name field should have the person's github username set as its value. The default name for the file is sign-off, but you do have the ability to name it something else (see input parameters for details). Make sure to place this file in <project-root>/.github.
{
"list": [
{
"name": "github-user",
"team": "team name"
},
{
"name": "github-user-2",
"team": "team name 2"
}
]
}A rule will need to be setup to block PRs from being merged until this action has passed. You can learn how to setup branch protection rules here.
Once the PR has gone through the test process, the team member listed in the user list for your team (more than likely a member of QA) will approve the PR. Once the approval has been submitted, the action will run. It will remove the label from the PR and the action will give the green light for the PR to be merged.
If for some reason someone on your team that is on the user list isn't available to approve the PR, then you can manually remove the label from the PR and get the green light as well. If this is the route needed for moving forward, Sign-off will post in the action's summary who removed the label.