🪐 OrbitScout

GitHub workflow-optimizing bot for the Orbit organization

Design-first workflow automation — because great tools should be beautiful too.

---

✦ About

OrbitScout is a GitHub App bot that optimizes issue and pull request workflows across the Orbit organization. It works around GitHub's binary permission model — allowing any contributor to self-assign issues, manage labels, and receive automated notifications, without requiring full write access to the repository.

Inspired by zulipbot, built from the ground up with modern tooling for the Orbit ecosystem.

---

✦ Features

Feature	Description
🎯 Issue Claiming	Self-assign issues via comments — no write access needed
🏷️ Label Management	Add/remove labels via commands, with protected label support
👋 Welcome Messages	Greet first-time contributors on their first issue or PR
🚀 In-Progress Tracking	Automatically tag claimed issues with status labels
🔒 Permission Guards	Protected labels, claim limits, and self-only labeling
⚙️ Per-Repo Config	Each repo can customize behavior via .github/orbitscout.yml

Coming Soon (Phase 2)

Feature	Description
⏰ Stale Detection	Auto-warn and unassign inactive issues/PRs
⚠️ Merge Conflicts	Notify PR authors about merge conflicts
📋 PR Checklist	Enforce PR requirements before review
🗺️ Area Labels	Auto-label PRs based on file paths changed

---

✦ Commands

All commands are triggered by mentioning @OrbitScout in an issue or PR comment.

Command	Description	Context
@OrbitScout claim	Assign yourself to the issue	Issues
@OrbitScout take	Alias for claim	Issues
@OrbitScout abandon	Unassign yourself from the issue	Issues/PRs
@OrbitScout drop	Alias for abandon	Issues/PRs
@OrbitScout label "bug"	Add the bug label	Issues/PRs
@OrbitScout label "bug" "urgent"	Add multiple labels	Issues/PRs
@OrbitScout unlabel "bug"	Remove the bug label	Issues/PRs
@OrbitScout help	Show available commands	Issues/PRs

Example Interaction

👤 Contributor:  @OrbitScout claim

🤖 OrbitScout:   ✅ @contributor — you've been assigned to this issue.
                 Happy building! 🪐

👤 Contributor:  @OrbitScout label "bug" "good first issue"

🤖 OrbitScout:   🏷️ @contributor — added labels: `bug`, `good first issue`

---

✦ Configuration

Each repository can customize OrbitScout by creating a .github/orbitscout.yml file. Any values not specified will use the defaults.

📄 Full Configuration Reference

# .github/orbitscout.yml

# Issue commands
issues:
  commands:
    claim:
      enabled: true
      aliases:
        - claim
        - take
      # Max issues a new contributor can claim simultaneously
      maxClaimsForNewContributors: 2
      # Label applied when an issue is claimed
      inProgressLabel: "🚀 in progress"
    abandon:
      enabled: true
      aliases:
        - abandon
        - unclaim
        - drop
    label:
      enabled: true
      aliases:
        - label
        - add
      # If true, only issue/PR creators can modify labels
      selfOnly: false
      # Labels that only collaborators can add/remove
      protectedLabels:
        - "priority/critical"
        - "status/blocked"
    unlabel:
      enabled: true
      aliases:
        - unlabel
        - remove

# Stale issue/PR management (Phase 2)
inactivity:
  issues:
    warningDays: 14
    abandonDays: 21
  pullRequests:
    reminderDays: 30

# Merge conflict detection (Phase 2)
mergeConflicts:
  enabled: true
  label: "❌ has conflicts"

# Welcome messages for first-time contributors
welcome:
  enabled: true
  newIssueMessage: >
    👋 Welcome to Orbit, @{user}! Thanks for opening your first issue here.
    Check out our [contributing guidelines](CONTRIBUTING.md) to get started.
  newPRMessage: >
    🎉 Welcome to Orbit, @{user}! Thanks for your first pull request!
    A maintainer will review it soon. 🪐

# Area labels based on file paths (Phase 2)
areaLabels:
  enabled: false
  mappings:
    "src/fonts/**": "area/fonts"
    "scripts/**": "area/tooling"
    "docs/**": "area/docs"

---

✦ Getting Started & Deployment

OrbitScout is a Machine User Bot (authenticated via a Personal Access Token), completely decoupled from the GitHub App/Probot framework.

• To deploy OrbitScout for your organization: Follow our step-by-step Deployment Guide.
• To run OrbitScout locally for development: Check out our Contributing Guidelines.

---

✦ Contributing

We welcome contributions! Please read our Contributing Guidelines before submitting a pull request.

---

✦ License

MIT — built by the Orbit team.

---

✦ Credits

• Inspired by zulipbot by the Zulip team
• Built with Octokit & Express — acts as a Machine User
• Part of the Orbit design-first development ecosystem

---

🪐 Orbit — Design First. Zero Friction. Open Source.

Website · GitHub · LinkedIn