Label automation at your fingertips
Tags: actionshackathon21, github, opensource, doka
Published: 2021-12-08 21:38:47

---
title: Label automation at your fingertips
published: true
description: Label PRs in monorepos, modular applications, or content-based projects using easy-to-grasp action
tags: actionshackathon21, github, opensource, doka
---

![Image of dog created using font characters](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/mei9bas7nk6dcgcforwm.png)

[Doka](https://doka.guide/) is a Russian web developer's newest open-source handbook. We are new, so we had to create our workflow from scratch. We are demanding labels users, and we can hook you up too!

## Problem

When a project has a sophisticated multi-stage review process, the workflow quickly goes out of hand - pull requests get lost, and the review time grows, leading to unhappy contributors.

For example, In Doka's case, we have four sections of our website, each with a dedicated editor: HTML, CSS, JS, and tools. On top of that, there is a responsible for demos, an illustrator, and a publishing editor. We wanted to have one place where they can go to understand what job is pending.

In most of the repos, you probably want to know:
* the scope a particular PR has;
* what parts of the project it touches;
* whether it removes or edits files you don't want to be touched.

## Options

What are the options Github gives us? There are not many: codeowners and labels.

### Codeowners

Assignee and reviewers are similar. Somebody assigns a person responsible for the PR, and you can filter the list by your name. 

Reviewers can even be automated using a CODEOWNERS file at the root of the project. Code owners are defined based on files and have to get approval from the owner. 

The significant advantage of that approach is that the reviewer gets notifications about the PR. 

However, the more code you have, the more complicated the file becomes. It also bloats the notification panel because you automatically watch every PR you were assigned to.

### Labels

Labels are a non-restrictive approach to marking PRs, and they do not require anything from your side to provide insights about the PR content.

We found they are a great companion of code owners when cooked well. The label-scoped pull requests and issues have a unique filter URL, which a person can bookmark and see only their scope of work.

However, you need to be careful to not create too many, making them impossible to grasp and use by contributors.

The standard approach is to label PRs by task type (bug, feature, question, etc.) and by complexity (internal, good first issue).

We decided to add more essential labels:
* scope - module, section, component;
* type work needed - design review, editor check, or demo creation;
* restricted files touched — e.g., removed `package-lock.json`;
* add your project-specific labels - we also add a label that reflects the `tag` key from markdown files' frontmatter.

## Solution

![Use code owners and labels](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/b0s01p814jse5uupma0r.png)

We took the best from both worlds and followed the approach we found extremely useful:

1. Define code owners for parts that are critical, no less than two people per section;
1. Provide additional information automatically through labels.

We couldn't find the best automatic labeler, so we wrote it ourselves. With it, you can automate both sides of the equation. It has built-in core modules:

- label PR based on file paths in a PR and their status (added, removed, renamed, modified);
- assignee;
- front matter from any statically generated engine (we use 11ty)

You can add yours!

{% github https://github.com/doka-guide/doka-labeler %}

### Example

Let's consider a blog where posts are placed in the _posts_ folder. Each post can be either an article or a daily log which is defined in the `tags` front-matter key (as in dev.to). 

We want to label PRs:
* with the type of post it contains;
* as "needs design review" when a new image is added;
* an alarming label when critical files are removed.

Here is how we can organize it using Doka Labeler. 

#### Create workflow

Create a workflow definition file at `.github/workflows/labeler.yml`

{% collapsible _labeler.yml_ %} 

```yml
name: Labeler

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:

jobs:
  labeling:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run labeler
        uses: doka-guide/doka-labeler@v1
        with:
          token: "${{ secrets.GITHUB_TOKEN }}"
          config: ".github/labeler-config.yml"
```
{% endcollapsible %}

#### Define labeling rules

Create a config file at `.github/labeler-config.yml`:

{% collapsible _labeler-config.yml_ %}

```yml
# set "article" label when front matter has "article"
"article":
  - meta:
      tags: "article"

# set "daily log" label from front matter:
"daily log":
  - meta:
      tags: "daily-log"


# "design review" if images are added or modified:
"design review":
  - files:
      added: *.(jpg|jpeg|svg|png)
      modified: *.(jpg|jpeg|svg|png)

# alarm when critical files are removed
"🚨 alarm":
  - strategy:
      - create-if-missing # create this label if it does not exist
  - files:
      modified:
        - package-lock.json
      removed:
        - package-lock.json
        - package.json
        - .github/**
```
{% endcollapsible %}

We have more examples [in the repository](https://github.com/doka-guide/doka-labeler/tree/main/examples)!

### Submission Category: 
Maintainer Must-Haves

### Gratitude

People:
{% user igsekor %}
{% user nlopin %}

Libraries used:
- [Checkout Action](https://github.com/actions/checkout)
- [Picomatch](https://github.com/micromatch/picomatch) instead of minimatch
- [front-matter](https://github.com/jxson/front-matter) parser
- [Vercel's ncc](https://github.com/vercel/ncc) compiler