GitHub Actions workflow to sync GitHub labels in the declarative way.

By using this workflow, you can sync current labels with labels configured in a YAML manifest.

Usage

Create YAML manifest of GitHub labels

- name: bug
  description: Something isn't working
  color: d73a4a
- name: documentation
  description: Improvements or additions to documentation
  color: 0075ca
- name: duplicate
  description: This issue or pull request already exists
  color: cfd3d7

The default file path is .github/labels.yml, but you can specify any file path with jobs.<job_id>.steps.with.manifest.

To create manifest of the current labels easily, using label-exporter is recommended.

Renaming labels

If you want to rename a label, you can set an alias in the manifest. For example, if you want to rename the label bug to Type: bug, you would use a manifest like this:

- name: Type: bug
  alias: bug
  description: Something isn't working
  color: d73a4a

Renaming labels makes it easier to adopt a new taxonomy if you have issues and pull requests using the old label names. Since you're renaming labels rather than deleting and creating new ones, existing pull requests and issues will keep their labels, but will adopt the new name.

You can also set multiple aliases, which can be useful when reusing a configuration across multiple repositories, each of which may have a different existing label. For example:

- name: Type: bug
  aliases:
    - bug
    - defect
    - "Seriously, what was I thinking?"
  description: Something isn't working
  color: d73a4a

Import statements

To reuse some common configurations across repositories, add an item with just one field called import, which contains a path to another yaml file. The contents of the imported file will be treated as if they appeared in the main file. For example:

# Common label definitions for all projects, such as "Type: bug".
- import: common.yaml

# Labels specific to this project:
- name: Platform: iOS
  description: Issues specific to iOS
  color: d7ea4a

Create Workflow

An example workflow is here.

name: Sync labels
on:
  push:
    branches:
      - master
    paths:
      - path/to/manifest/labels.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: micnncim/action-label-syncer@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          manifest: path/to/manifest/labels.yml

If a label color or description changes, the same label is updated with the new color or description. If a label name changes, the previous label is deleted by default. Also all existing labels which not listed in manifest will be deleted by default. All issues and PRs that were previously labeled with this label are now unlabeled.

You can add jobs.<job_id>.steps.with.prune: false in order to preserver all existing labels which is not mentioned in manifest, in this case when a label will be renamed old label will be not deleted.

Sync labels on another repository

It is also possible to specify a repository or repositories as an input to the action. This is useful if you want to store your labels somewhere centrally and modify multiple repository labels.

Note: The default GITHUB_TOKEN will not have permissions to operate on other repositories so you must specify a personal access token in your secrets.

name: Sync labels
on:
  push:
    branches:
      - master
    paths:
      - path/to/manifest/labels.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: micnncim/action-label-syncer@v1
        with:
          manifest: path/to/manifest/labels.yml
          repository: |
              owner/repository-1
              owner/repository-2
          token: ${{ secrets.PERSONAL_TOKEN }}

Project using action-label-syncer

• cloudalchemy/ansible-prometheus
• cloudalchemy/ansible-grafana
• cloudalchemy/ansible-node-exporter
• cloudalchemy/ansible-fluentd
• cloudalchemy/ansible-alertmanager
• cloudalchemy/ansible-blackbox-exporter
• cloudalchemy/ansible-pushgateway
• cloudalchemy/ansible-coredns
• sagebind/isahc
• JulienBreux/baleia
• Simplify4U
• Poeschl's Home Assistant Addons
• The Guild - Master Labels
• The Guild - GraphQL Codegen
• The Guild - GraphQL ESLint
• The Guild - Apollo Angular
• The Guild - GraphQL Config
• The Guild - GraphQL Mesh
• The Guild - GraphQL Modules
• The Guild - GraphQL Inspector
• The Guild - GraphQL Tools
• The Guild - GraphQL Scalars
• The Guild - Whatsapp Clone
• The Guild - GraphQL CLI
• The Guild - SOFA

If you're using action-label-syncer in your project, please send a PR to list your project!

See also

• Prow
• actions/labeler
• lannonbr/issue-label-manager-action
• b4b4r07/github-labeler

Note

Icon made by bqlqn from www.flaticon.com