Require Labels Action
Tags: github, githubactions
Published: 2021-01-23 18:51:21

---
title: Require Labels Action
published: true
date: 2021-01-22 18:25:17 UTC
tags: github,githubactions
canonical_url: https://michaelheap.com/require-pr-labels/
series: Action Spotlight
---

This week’s featured action is one of my own! [Require labels](https://github.com/marketplace/actions/require-labels) is an action that can be used to enforce workflows that require labels to be added to a pull request.

## What does it do?

Taken directly from the action’s README:

> This action allows you to fail the build if/unless a certain combination of labels are applied to a pull request.

It’s a fairly generic problem to solve, but let’s think about cases when this may be useful. Here are some examples from projects [found on GitHub](https://github.com/search?q=mheap%2Fgithub-action-required-labels&type=code)

- Prevent merging if a `wip` label is added
- Require a PR to be tagged with a label indicating the semantic versioning level for the changes contained e.g. `semver:major`, `semver:minor` or `semver:patch`
- Indicate the priority of a PR that needs reviewing with a `P1`, `P2` or `P3` label

## How does it work?

The action has three required inputs; `labels`, `mode` and `count`. All three [are required inputs](https://github.com/mheap/github-action-required-labels/blob/cb60d6f1ee511dc5c59a720cdfee432d783f6184/index.js), and `mode` must be equal to [`exactly`, `minimum` or `maximum`](https://github.com/mheap/github-action-required-labels/blob/cb60d6f1ee511dc5c59a720cdfee432d783f6184/index.js#L22-L28). If any inputs are empty or an invalid `mode` is provided the action will fail (and the PR status checks will not pass).

If all of the required inputs are provided, the action reads the provided event payload and [extracts the name](https://github.com/mheap/github-action-required-labels/blob/cb60d6f1ee511dc5c59a720cdfee432d783f6184/index.js#L30-L32) of each applied label. Next, it [calculates the intersection](https://github.com/mheap/github-action-required-labels/blob/cb60d6f1ee511dc5c59a720cdfee432d783f6184/index.js#L34) of the labels on the pull request and the labels provided in the `labels` input. This provides a list of labels that are both applied to the PR **and** present in the `labels` input.

Finally, it’s time to check that the applied labels meet the rules that were set. The easiest one to check is `exactly`. If the number of [matching labels applied is not equal](https://github.com/mheap/github-action-required-labels/blob/cb60d6f1ee511dc5c59a720cdfee432d783f6184/index.js#L36-L41) to the `count` input, the action fails.

Next, if the [number of applied labels is lower](https://github.com/mheap/github-action-required-labels/blob/cb60d6f1ee511dc5c59a720cdfee432d783f6184/index.js#L43-L48) than `count` and we’re using the `minimum` mode, fail the build.

Then finally we [check that the number of labels is higher](https://github.com/mheap/github-action-required-labels/blob/cb60d6f1ee511dc5c59a720cdfee432d783f6184/index.js#L50-L55) than `count` when running in `maximum` mode. If not, once again the build is failed.

If at this point we haven’t failed the build, there are no more checks to run and we can assume that all of the checks have passed and [mark the build as a success](https://github.com/mheap/github-action-required-labels/blob/cb60d6f1ee511dc5c59a720cdfee432d783f6184/index.js#L57).

## Useful links

- [GitHub Marketplace](https://github.com/marketplace/actions/require-labels)
- [GitHub Repo](https://github.com/mheap/github-action-required-labels)
- [Example Usage](https://github.com/mheap/github-action-required-labels#examples)