label-checker

Label Checker

GitHub Action to check pull requests (PRs) for the presence or absence of specified labels

Why another label checker?

• We couldn't find another label checker that had all our 4 check types (one_of, none_of, all_of, any_of)

• Speed: the Docker image used for the checks is only 2.7 MB, so the checks are blazingly fast (c. 3 seconds)

Using the Label Checker action

Using this action is as simple as:

1. create a .github\workflows directory in your repository

2. create a YAML file in the .github\workflows directory (file name can be anything you like, with either a .yml or .yaml file extension), with this example content:

   ---
   name: Label Checker
   on:
     pull_request:
       types:
         - opened
         - synchronize
         - reopened
         - labeled
         - unlabeled
   
   jobs:
   
     check_labels:
       name: Check labels
       runs-on: ubuntu-latest
       steps:
         - uses: docker://agilepathway/pull-request-label-checker:latest
           with:
             one_of: major,minor,patch
             repo_token: ${{ secrets.GITHUB_TOKEN }}
   

3. customise the label checks in the with section of the YAML file to fit your needs

   (see the checks section below for the different checks you can configure)

Checks

There are 4 types of label checks available:

• one_of (PRs must have exactly one of these labels)

• none_of (PRs must have none of these labels)

• all_of (PRs must have all of these labels)

• any_of (PRs must have one or more of these labels)

You can have as many of the checks configured in the same YAML file as you like.

Examples

• Semantic versioning: one_of: major,minor,patch

• Each PR must be a bug or an enhancement: one_of: bug,enhancement

• Prohibit certain labels: none_of: invalid,wontfix,duplicate,question

• Require each PR to have a certain label: all_of: enhancement

  or labels: all_of: enhancement,reviewed

• Require each PR to have one or more of these labels: any_of: documentation,enhancement,bug

• Combine multiple checks:

  with:
    one_of: major,minor,patch
    none_of: invalid,wontfix,duplicate,question
    any_of: documentation,enhancement,bug
    repo_token: ${{ secrets.GITHUB_TOKEN }}
  

• Combine multiple checks of the same type:

  jobs:
  
    check_semver_label:
      name: Check for semantic version label
      runs-on: ubuntu-latest
      steps:
        - uses: docker://agilepathway/pull-request-label-checker:latest
          with:
            one_of: major,minor,patch
            repo_token: ${{ secrets.GITHUB_TOKEN }}
  
    check_pull_request_type:
      name: Check for pull request type label
      runs-on: ubuntu-latest
      steps:
        - uses: docker://agilepathway/pull-request-label-checker:latest
          with:
            one_of: bug,enhancement
            repo_token: ${{ secrets.GITHUB_TOKEN }}
  

Allow failure mode

You can set the label checker to not fail the build, even when a label check fails, and then use an if condition in a subsequent step or job to conditionally do something or not. For example: check if a pull request has a preview label and then only deploy an ephemeral environment if so.

Set the allow_failure mode as an input parameter in the with section: allow_failure: true

Example:

steps:
  - id: preview_label_check
    uses: docker://agilepathway/pull-request-label-checker:latest
    with:
      all_of: preview
      repo_token: ${{ secrets.GITHUB_TOKEN }}
      allow_failure: true
  - if: steps.preview_label_check.outputs.label_check == 'success'
    run: echo deploy to ephemeral environment

The label checker always exposes the label_check step output variable, regardless of whether allow_failure is set or not. The variable has a value of either success or failure which can then be queried in subsequent steps, as in the above example.

GitHub Enterprise

To use this label checker with GitHub Enterprise, specify the GitHub Enterprise GraphQL URL in an input, e.g. for Enterprise Cloud:

jobs:

  check_labels:
    name: Check labels
    runs-on: ubuntu-latest
    steps:
      - uses: docker://agilepathway/pull-request-label-checker:latest
        with:
          github_enterprise_graphql_url: https://api.github.com/graphql
          one_of: major,minor,patch # just an example
          repo_token: ${{ secrets.GITHUB_TOKEN }}

or for Enterprise Server:

jobs:

  check_labels:
    name: Check labels
    runs-on: ubuntu-latest
    steps:
      - uses: docker://agilepathway/pull-request-label-checker:latest
        with:
          github_enterprise_graphql_url: https://<hostname>/api/graphql
          one_of: major,minor,patch # just an example
          repo_token: ${{ secrets.GITHUB_TOKEN }}

Suggestions / bug reports / contributions

The project is open source and all contributions are very welcome 🙂 💥 👍

• How to report a bug or suggest a new feature

• How to make a contribution

• Local development

• Running the tests

Updating dependencies

See the DEPENDENCIES.md