RepoPilot 🚀

Automate common GitHub repository tasks with a single command.

RepoPilot is an open-source Node.js tool that talks to the GitHub REST API and handles the repetitive maintenance work that slows down maintainers: labelling issues, chasing stale threads, welcoming new contributors, and enforcing pull request standards.

---

Features

Feature	Description
🏷️ Auto-Labeler	Labels issues automatically based on keyword rules
🕰️ Stale Issue Detector	Flags issues with no activity after a configurable number of days
👋 Welcome Bot	Posts a greeting comment on first-time contributor PRs
✅ PR Format Checker	Verifies PRs contain required sections before review
📊 Contributor Summary	Generates a ranked list of contributors by commit count

---

Table of Contents

1. Prerequisites
2. Installation
3. Setting Up a GitHub Personal Access Token
4. Configuration
5. Usage
6. Architecture
7. Running Tests
8. Contributing
9. License

---

Prerequisites

• Node.js v16 or higher
• npm v7 or higher
• A GitHub account with access to the repository you want to automate

Check your versions:

node --version
npm --version

---

Installation

# 1. Clone the repository
git clone https://github.com/your-username/repo-pilot.git
cd repo-pilot

# 2. Install dependencies
npm install

# 3. Copy the environment template
cp .env.example .env

---

Setting Up a GitHub Personal Access Token

RepoPilot needs a GitHub Personal Access Token (PAT) to authenticate API requests.

1. Go to https://github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Give it a descriptive name, e.g. repopilot-local
4. Set an expiry date (90 days is a reasonable choice)
5. Under Scopes, tick:
   • repo — full repository access (read + write issues, PRs, labels)
   • read:org — needed if your repository belongs to an organisation
6. Click "Generate token" and copy the token immediately (it won't be shown again)
7. Open your .env file and paste the token as the value of GITHUB_TOKEN

⚠️ Never commit your .env file or paste your token into source code. The .gitignore in this project already excludes .env.

---

Configuration

Open the .env file you copied from .env.example and fill in your values:

# Required
GITHUB_TOKEN=ghp_yourTokenHere
GITHUB_OWNER=your-github-username
GITHUB_REPO=your-repository-name

# Stale bot — optional, defaults shown
STALE_DAYS=30
STALE_LABEL=stale
STALE_MESSAGE=This issue has been automatically marked as stale due to inactivity.

# Feature toggles
AUTO_LABEL_ENABLED=true
WELCOME_BOT_ENABLED=true

# PR checker — comma-separated required section headings
PR_REQUIRED_SECTIONS=## Description,## Testing,## Checklist

Custom label rules

Label rules are defined in src/config.js under config.labeler.rules. Each rule has a keywords array and a label string:

{ keywords: ['bug', 'error', 'crash'], label: 'bug' }

To add or change rules, edit that array. (See Issue #9 if you'd like to make rules configurable via a JSON file without editing source code.)

---

Usage

Run everything at once

npm start
# or
node examples/runAutomation.js

Run individual bots

# Label open issues by keyword
npm run label

# Find and mark stale issues
npm run stale

# Greet first-time contributors on open PRs
npm run welcome

Run individual bots directly

node automation/labeler.js
node automation/staleIssueBot.js
node automation/welcomeBot.js

Automate with GitHub Actions

Create .github/workflows/repopilot.yml in your repository:

name: RepoPilot

on:
  schedule:
    - cron: '0 6 * * *'   # runs every day at 06:00 UTC
  workflow_dispatch:       # allows manual trigger from the Actions tab

jobs:
  automate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm install

      - run: npm start
        env:
          GITHUB_TOKEN: ${{ secrets.REPOPILOT_TOKEN }}
          GITHUB_OWNER: ${{ github.repository_owner }}
          GITHUB_REPO:  ${{ github.event.repository.name }}

Add your PAT as a repository secret named REPOPILOT_TOKEN in Settings → Secrets → Actions.

---

Architecture

repo-pilot/
├── src/
│   ├── config.js            # Reads .env and exports structured config
│   ├── utils.js             # Pure helpers: dates, strings, logger
│   ├── githubClient.js      # GitHub REST API transport layer (Axios)
│   ├── issueManager.js      # Issue automation logic
│   ├── prManager.js         # PR automation logic
│   └── automationEngine.js  # Orchestrator — runs all tasks in sequence
│
├── automation/              # Standalone runnable bot scripts
│   ├── labeler.js
│   ├── staleIssueBot.js
│   └── welcomeBot.js
│
├── examples/
│   └── runAutomation.js     # Main entry point
│
└── tests/
    └── automation.test.js   # Unit tests (pure functions only)

Request flow

.env → config.js → automationEngine.js
                        ├── issueManager → githubClient → GitHub API
                        └── prManager   → githubClient → GitHub API

All HTTP calls are isolated in src/githubClient.js. Business rules live in issueManager.js and prManager.js. The engine in automationEngine.js calls those managers and reports results. This layered design means you can swap the HTTP client or mock the GitHub layer in tests without touching business logic.

---

Running Tests

npm test

The test suite exercises pure utility functions without making real API calls. See tests/automation.test.js for details.

The test suite is minimal by design. Adding comprehensive tests with Jest mocking is listed as Issue #10 — contributions welcome!

---

Contributing

We welcome contributions of all sizes! Please read CONTRIBUTING.md for the full guide.

Quick start:

git checkout -b feat/your-feature
# make your changes
npm test
git commit -m "feat(scope): describe your change"
git push origin feat/your-feature
# open a Pull Request

Browse issues.md for a list of 15 curated development tasks ranging from beginner-friendly (Trivial) to advanced (High).

---

License

MIT © RepoPilot Contributors