Require Labels Action

Fail the build unless a certain combination of labels are applied to a pull request

This week’s featured action is one of my own! 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

  • 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, and mode must be equal to exactly, minimum or maximum. 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 of each applied label. Next, it calculates the intersection 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 to the count input, the action fails.

Next, if the number of applied labels is lower than count and we’re using the minimum mode, fail the build.

Then finally we check that the number of labels is higher 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.

Useful links