Smart Labeler

A GitHub Action that labels new issues and pull requests with your repository's existing labels. It reads the title and body (plus the changed file paths, for PRs) and asks TypeSafe's Jev model which labels fit.

It never creates or removes labels. It only adds existing ones.

How it works

Label names are split into a group and a name by a separator (default :):

• At most one label per group is applied.
• A group is skipped when the issue or PR already has a label from it.
• Everything is sent in one TypeSafe request.

A label is applied when the model's probability is at least threshold. If more labels pass than max-labels allows, the highest-probability ones win.

Setup

1. Get a TypeSafe API key and add it as the repository secret TYPESAFE_API_KEY.
2. Add examples/smart-label.yml as .github/workflows/smart-label.yml:

name: Smart Label

on:
  issues:
    types: [opened]
  pull_request_target:
    types: [opened]

permissions:
  issues: write
  pull-requests: write

jobs:
  label:
    runs-on: ubuntu-latest
    steps:
      - uses: <owner>/smart-labeler@v1
        with:
          typesafe-api-key: ${{ secrets.TYPESAFE_API_KEY }}

Why pull_request_target? On pull_request, PRs from forks get neither secrets nor a write token, so labeling would fail. pull_request_target runs in the context of the base repository. That is safe here because this action never checks out or runs the PR's code; it only reads the PR's metadata and file list through the API. Don't add a checkout of the PR head to this job.

Inputs

Outputs

Each run also writes a job summary with the pick, probability and runner-up for every group, and the probability for every ungrouped label.

Errors and warnings

• A TypeSafe or GitHub API error fails the step.
• A group with more than 254 labels (the limit for one choice question) is skipped with a warning; everything else still runs. Set fail-on-warning: true to turn warnings into a failed step.

Getting good results

• Write label descriptions. The model sees each label's name and description. type:bug — Something that used to work is broken gets far better results than a bare name.
• Group labels that exclude each other. priority:high / priority:low belong in one group. Labels that can apply together (frontend and backend, say) should be ungrouped so each is judged on its own.
• Tune threshold with dry-run. Start with dry-run: true and read the job summaries on a few real issues. Raise the threshold if wrong labels get through; lower it if obvious ones are missed.

Development

npm ci
npm run typecheck
npm test
npm run build   # bundles to dist/ — commit the result

dist/ must be committed, since GitHub runs dist/index.js directly. CI fails if it is out of date.

To try a local run, set the INPUT_* and GITHUB_* variables the Actions runtime would provide:

env GITHUB_EVENT_NAME=issues GITHUB_EVENT_PATH=./event.json GITHUB_REPOSITORY=owner/repo \
  "INPUT_TYPESAFE-API-KEY=$TYPESAFE_API_KEY" "INPUT_GITHUB-TOKEN=$(gh auth token)" "INPUT_DRY-RUN=true" \
  node dist/index.js

On Git Bash for Windows, prefix with MSYS_NO_PATHCONV=1 if the separator is /.