Skip to content

Latest commit

 

History

History
311 lines (233 loc) · 6.2 KB

README.md

File metadata and controls

311 lines (233 loc) · 6.2 KB
Raw

super-labeler-action

A superpowered issue and pull request labeler for Github Actions.

Super Labeler allows you to declaratively define your repository's labels, and when to apply them, in a config file that's checked into your repository.

Getting Started

Create a new Github Actions workflow at .github/workflows/label.yml:

Click to show example workflow

Note: actions/checkout must be run first so that the labeler action can find your config file.

on:
  issues: [opened, edited, closed, reopened]
  pull_request:
    types: [opened, edited, closed, reopened, ready_for_review, synchronize]

jobs:
  label:
    runs-on: ubuntu-latest
    name: Label issues and pull requests
    steps:
      - uses: actions/checkout@v2
      - uses: IvanFon/super-labeler-action@v1
        with:
          github-token: '${{ secrets.GITHUB_TOKEN }}'

Now create the labeler config file at .github/labels.json:

Click here to show example config 
{
  "labels": {
    "example": {
      "name": "example",
      "colour": "#00ff00",
      "description": "Example label"
    }
  },
  "issue": {
    "example": {
      "requires": 2,
      "conditions": [
        {
          "type": "titleMatches",
          "pattern": "example"
        },
        {
          "type": "isOpen"
        }
      ]
    }
  },
  "pr": {
    "example": {
      "requires": 1,
      "conditions": [
        {
          "type": "isDraft",
          "value": false
        }
      ]
    }
  }
}

Be sure that Github Actions is enabled for in your repository's settings. Super Labeler will now run on your issues and pull requests.

Index

How it Works

Whenever Super Labeler runs, it will first add and update your repository's labels to match your config. Then it will go through each label's conditions to determine if it should apply or remove that label.

Each label has a list of conditions that must be met for it to be applied. You must specify the minimum number of conditions that must be met for the label to be applied.

Each label has a key, which can be different from it's name. This key should be in plaintext, and will be used to refer to the given label when defining your conditions. For example, given the following labels definition:

{
  "labels": {
    "bugfix": {
      "name": "Bugfix! 🎉",
      "colour": "ff0000",
      "description": "Fixes a bug."
    }
  }
}

While the label's name, which will be displayed on Github, is "Bugfix! 🎉", to be able to easily refer to it from our conditions, we would use it's key, which is just bugfix:

{
  "pr": {
    "bugfix": {
      "requires": 1,
      "conditions": [
        {
          "type": "branchMatches",
          "pattern": "^bugfix"
        }
      ]
    }
  }
}

Config File Format

The config object contains three keys:

  • labels: Your repository's labels, which will be automatically created and updated by Super Labeler
  • issue: Labels to apply to issues, and their conditions
  • pr: Labels to apply to pull requests, and their conditions

Take a look at the examples in this file to get a feel for how to configure it. The below Typescript interface, which is used by this action, may also be helpful:

Click to show Typescript config interface 
interface Config {
  labels: {
    [key: string]: {
      name: string,
      colour: string,
      description: string,
    },
  };
  issue: {
    [key: string]: {
      requires: number,
      conditions: IssueCondition[],
    },
  };
  pr: {
    [key: string]: {
      requires: number,
      conditions: PRCondition[],
    },
  };
}

Using Regex Patterns

Many conditions use regular expressions (usually with a pattern parameter). Since these regular expressions are passed in through JSON strings, there are some things to pay attention to.

Special characters must be double escaped: pattern: "\\W+$" is equivalent to the Regex: /\W+$/.

If you want to use flags, use the following format: pattern: "/^wip:/i" is equivalent to the Regex: /^wip:/i.

Available Conditions

branchMatches

Applies to: pull requests

Checks if branch name matches a Regex pattern.

Example:

{
  "type": "branchMatches",
  "pattern": "^bugfix\\/"
}

creatorMatches

Applies to: issues and pull requests

Checks if an issue or pull request's creator's username matches a Regex pattern.

Example:

{
  "type": "creatorMatches",
  "pattern": "^foo"
}

descriptionMatches

Applies to: issues and pull requests

Checks if an issue or pull request's description matches a Regex pattern.

Example:

{
  "type": "descriptionMatches",
  "pattern": "foo.*bar"
}

filesMatch

Applies to: pull requests

Checks if the files modified in the pull request match a glob.

Globs are matched using the minimatch library.

Example:

{
  "type": "filesMatch",
  "glob": "src/foo/**/*"
}

isDraft

Applies to: pull requests

Checks if a pull request is a draft.

Example:

{
  "type": "isDraft",
  "value": true
}

isLocked

Applies to: issues and pull requests

Checks if an issue or pull request is locked.

Example:

{
  "type": "isLocked",
  "value": true
}

isOpen

Applies to: issues and pull requests

Checks if an issue or pull request is open or closed.

Example:

{
  "type": "isOpen",
  "value": true
}

titleMatches

Applies to: issues and pull requests

Checks if an issue or pull request's title matches a Regex pattern.

Example:

{
  "type": "titleMatches",
  "pattern": "/^wip:/i"
}

back to top