Skip to content

Getting started

Prerequisites

  • Python 3.11 or later
  • uv (install with curl -LsSf https://astral.sh/uv/install.sh | sh)
  • A GitHub account with permission to create a GitHub App

Install

Clone the repo and install dependencies:

git clone https://github.com/gregology/developer.git
cd developer
uv sync

Create a GitHub App

Developer authenticates as a GitHub App, not as your personal account. This keeps permissions scoped and lets it act as a bot identity.

  1. Go to Settings -> Developer settings -> GitHub Apps -> New GitHub App
  2. Give it a name (e.g. "Developer")
  3. Set the homepage URL to anything (your repo works fine)
  4. Under Permissions, grant:
    • Issues: Read & Write
    • Pull requests: Read & Write
    • Contents: Read & Write
  5. Click Create GitHub App
  6. On the app's settings page, note the App ID
  7. Scroll down and click Generate a private key -- save the .pem file
  8. Install the app on your account or org, note the Installation ID from the URL

Configure credentials

cp example.env .env

Fill in your .env:

GITHUB_APP_ID=123456
GITHUB_INSTALLATION_ID=789012

# Paste the PEM contents directly, or use a file path
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----"

The .env file is gitignored. Don't commit it.

Add a repo

Copy the example config and customize it:

cp example.developer.yaml developer.yaml

The developer.yaml file is gitignored -- it's your personal config, same pattern as example.env -> .env. Each repo needs GitHub coordinates, setup commands, and quality tools:

repos:
  my-project:
    github:
      owner: myorg
      repo: my-project
    setup:
      - uv sync
    quality_tools:
      - name: ruff
        cmd: [uv, run, ruff, check, src/]

See Configuration for the full format.

First run

Try a dry run to make sure everything is wired up:

developer review my-project 1 --dry-run

This will clone the repo, pull the PR diff, run the review pipeline, and print the review comment without actually posting it. If credentials or config are wrong, you'll get a clear error here.

Once that works, drop the --dry-run:

developer review my-project 1

Developer clones repos into a local repos/ directory on first run and pulls latest on subsequent runs. The directory is gitignored. Deleting it is safe -- it'll re-clone next time.

If your venv isn't activated

Prefix commands with uv run:

uv run developer resolve my-project 25