The Label Action allows you to automatically add or remove labels from pull requests based on validation results. This is useful for categorizing PRs, highlighting issues, or tracking progress through your workflow.

​
Configuration

​
add
string | string[]

Label(s) to add to the PR

​
remove
string | string[]

Label(s) to remove from the PR

​
Basic Usage

on_success:
  - label:
      add: ["valid-pr"]
      remove: ["needs-work"]

​
Examples

​
Simple Labeling

Add a label when validations pass:

on_success:
  - label:
      add: ["ready-for-review"]

​
Multiple Labels

Add multiple labels at once:

on_success:
  - label:
      add: ["validated", "ready-for-review", "passes-ci"]

​
Conditional Labeling

Add different labels based on different rules:

ruleset:
  - name: "Feature PR"
    when:
      - "pull_request.opened"
    if:
      - type: "title"
        match: "^feat: .*"
    on_success:
      - label:
          add: ["feature"]

  - name: "Bug Fix PR"
    when:
      - "pull_request.opened"
    if:
      - type: "title"
        match: "^fix: .*"
    on_success:
      - label:
          add: ["bug-fix"]

​
State Management

Manage PR state through labels:

ruleset:
  - name: "PR Approval State"
    when:
      - "pull_request_review.submitted"
    validate:
      - type: "approvals"
        count:
          min: 2
    on_success:
      - label:
          add: ["approved"]
          remove: ["needs-review", "changes-requested"]
    on_failure:
      - label:
          add: ["needs-review"]
          remove: ["approved"]

​
How It Works

1

Get Current Labels

The action retrieves the current labels on the PR

2

Calculate Changes

It determines which labels need to be added and which need to be removed

3

Update Labels

It updates the PR with the new set of labels

​
Use Cases

​
Workflow Status

Track PR status in your workflow:

ruleset:
  - name: "PR Status"
    when:
      - "pull_request.*"
    validate:
      - type: "title"
        match: "^(feat|fix|docs): .*"
      - type: "size"
        files: 15
    on_success:
      - label:
          add: ["ready-for-review"]
          remove: ["needs-work"]
    on_failure:
      - label:
          add: ["needs-work"]
          remove: ["ready-for-review"]

​
PR Size Categories

Categorize PRs by size:

ruleset:
  - name: "PR Size - Small"
    when:
      - "pull_request.opened"
      - "pull_request.synchronize"
    if:
      - type: "size"
        files:
          max: 5
        total:
          max: 100
    on_success:
      - label:
          add: ["size: small"]
          remove: ["size: medium", "size: large"]

  - name: "PR Size - Medium"
    when:
      - "pull_request.opened"
      - "pull_request.synchronize"
    if:
      - type: "size"
        files:
          min: 6
          max: 15
        total:
          min: 101
          max: 500
    on_success:
      - label:
          add: ["size: medium"]
          remove: ["size: small", "size: large"]

  - name: "PR Size - Large"
    when:
      - "pull_request.opened"
      - "pull_request.synchronize"
    if:
      - type: "size"
        files:
          min: 16
        total:
          min: 501
    on_success:
      - label:
          add: ["size: large"]
          remove: ["size: small", "size: medium"]

​
Component Labeling

Automatically label PRs based on the files they change:

ruleset:
  - name: "Component - Frontend"
    when:
      - "pull_request.opened"
      - "pull_request.synchronize"
    if:
      - type: "files"
        modified:
          match: "src/frontend/.*"
    on_success:
      - label:
          add: ["component: frontend"]

  - name: "Component - Backend"
    when:
      - "pull_request.opened"
      - "pull_request.synchronize"
    if:
      - type: "files"
        modified:
          match: "src/backend/.*"
    on_success:
      - label:
          add: ["component: backend"]

  - name: "Component - Documentation"
    when:
      - "pull_request.opened"
      - "pull_request.synchronize"
    if:
      - type: "files"
        modified:
          match: "docs/.*|README\\.md"
    on_success:
      - label:
          add: ["component: docs"]

​
Best Practices

Use consistent label naming schemes
Create labels in your repository before using them in rules
Use color-coding to make labels more visually informative
Document what your labels mean in your contributing guidelines

Avoid creating too many labels, as this can become confusing for contributors

​
Limitations

  • Labels must already exist in the repository
  • Label names are case-sensitive
  • You can’t create new labels through this action