🤖 AI Issue Labeler

Automatically label your GitHub issues the moment they're opened — no manual triage needed.

AI Issue Labeler analyzes issue titles and bodies using keyword heuristics (zero config, no API key needed) or optional AI (OpenAI / Groq) for smarter classification. It applies the right labels and posts a comment explaining why.

---

✨ Features

• Zero-config heuristic mode — works immediately with no API keys
• AI mode — connect OpenAI or Groq for context-aware classification
• 6 standard labels — bug, feature, documentation, question, enhancement, help wanted
• Label autocreation — missing labels are created automatically with proper colors
• Explains itself — posts a comment showing what labels were applied and why
• Label prefix support — namespace labels like ai:bug, ai:feature
• Graceful fallback — if AI fails, falls back to heuristics automatically
• Supports issue opened, edited, and reopened events

---

🚀 Quick Setup (3 steps)

Step 1 — Create the workflow file

Create .github/workflows/label-issues.yml in your repository:

name: 🤖 AI Issue Labeler

on:
  issues:
    types: [opened, edited, reopened]

jobs:
  label:
    runs-on: ubuntu-latest
    permissions:
      issues: write
      contents: read
    steps:
      - uses: ellitedom03/ai-issue-labeler@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

Step 2 — Commit and push

git add .github/workflows/label-issues.yml
git commit -m "Add AI Issue Labeler"
git push

Step 3 — Open an issue to test it!

That's it. The next time someone opens an issue, it will be automatically labeled. 🎉

---

🤖 Enable AI Mode (Optional)

For smarter, context-aware classification, provide an API key:

Using OpenAI

1. Get an API key from platform.openai.com
2. Add it as a repository secret: Settings → Secrets → New secret → name it OPENAI_API_KEY
3. Update your workflow:

- uses: ellitedom03/ai-issue-labeler@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    ai-api-key: ${{ secrets.OPENAI_API_KEY }}
    ai-provider: openai
    model: gpt-4o-mini   # cheap and accurate

Using Groq (Free Tier Available!)

1. Get a free API key from console.groq.com
2. Add it as GROQ_API_KEY in your repository secrets
3. Update your workflow:

- uses: ellitedom03/ai-issue-labeler@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    ai-api-key: ${{ secrets.GROQ_API_KEY }}
    ai-provider: groq
    model: llama-3.1-8b-instant   # fast and free

---

⚙️ Configuration Reference

Input	Required	Default	Description
github-token	✅ Yes	${{ github.token }}	GitHub token to read issues and apply labels
ai-api-key	❌ No	''	OpenAI or Groq API key. If omitted, uses keyword heuristics
ai-provider	❌ No	openai	AI provider: openai or groq
model	❌ No	provider default	Override the AI model. Defaults: gpt-4o-mini (OpenAI), llama-3.1-8b-instant (Groq)
post-comment	❌ No	true	Post a comment explaining applied labels (true/false)
label-prefix	❌ No	''	Prefix for label names. E.g. ai: → ai:bug, ai:feature
confidence-threshold	❌ No	0.3	Heuristic mode only: minimum confidence (0–1) to apply a label

Outputs

Output	Description
labels-applied	Comma-separated list of labels applied (e.g. bug,enhancement)
classification-source	How the issue was classified: heuristic or ai

---

🏷️ Labels Applied

Label	Color	Description
bug	🔴	Something isn't working (errors, crashes, unexpected behavior)
feature	🔵	New feature request or capability
documentation	🔵	Docs improvements, typos, unclear instructions
question	🟣	User asking how to do something
enhancement	🔵	Improvements to existing features, performance, UX
help wanted	🟢	Needs community help or contributions

Labels are created automatically if they don't exist in your repo.

---

📋 Example Workflow (Full Options)

name: 🤖 AI Issue Labeler

on:
  issues:
    types: [opened, edited, reopened]

jobs:
  label:
    name: Auto-Label Issue
    runs-on: ubuntu-latest
    permissions:
      issues: write
      contents: read
    steps:
      - name: AI Issue Labeler
        id: labeler
        uses: ellitedom03/ai-issue-labeler@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          ai-api-key: ${{ secrets.GROQ_API_KEY }}
          ai-provider: groq
          model: llama-3.1-8b-instant
          post-comment: 'true'
          label-prefix: ''
          confidence-threshold: '0.3'

      # Use the outputs in subsequent steps
      - name: Print applied labels
        run: |
          echo "Labels applied: ${{ steps.labeler.outputs.labels-applied }}"
          echo "Classified by: ${{ steps.labeler.outputs.classification-source }}"

---

🔍 How It Works

Heuristic Mode (default)

When no ai-api-key is provided, the action uses a keyword scoring system:

1. Each label has a list of keywords and phrases (e.g. bug → crash, error, not working, ...)
2. The issue title + body are scored against each label's keyword list
3. Labels above the confidence-threshold are applied
4. If no label scores above the threshold, the highest-scoring label is still applied

AI Mode

When an ai-api-key is provided:

1. The issue is sent to the AI model with a structured prompt
2. The model returns a JSON response with labels and reasoning
3. Labels are validated against the allowed set before being applied
4. If the AI call fails for any reason, the action falls back to heuristics

---

🛠️ Development

# Clone the repo
git clone https://github.com/ellitedom03/ai-issue-labeler.git
cd ai-issue-labeler

# Install dependencies
npm install

# Run tests
npm test

# Build the dist bundle (required before pushing changes)
npm run build

Project Structure

ai-issue-labeler/
├── action.yml          # Action metadata & inputs
├── src/
│   ├── index.js        # Main entry point
│   ├── classifier.js   # Heuristic + AI classification logic
│   └── labels.js       # Label management (create, apply, comment)
├── dist/
│   └── index.js        # Compiled bundle (ncc output — commit this!)
├── __tests__/
│   └── classifier.test.js
└── .github/
    └── workflows/
        ├── test.yml         # CI: tests + dist verification
        └── label-issues.yml # Demo: self-labels this repo's issues

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes and run npm test + npm run build
4. Commit the dist/ folder with your changes
5. Open a pull request

---

📄 License

MIT © ellitedom03

---

🌟 Show Your Support

If this action saves you time, consider:

• ⭐ Starring the repository
• 🐦 Sharing it with your team
• 🐛 Opening issues for bugs or feature requests