Getting started

This guide gets crab’d running on a repository in a few minutes. You’ll add a workflow, give it a model key, and mention crab’d on an issue.

Prerequisites

• A repository on GitHub or Forgejo.
• An API key for at least one model provider (for example ANTHROPIC_API_KEY or OPENAI_API_KEY), stored as a CI secret.

Add the workflow

Pick the tab for your forge and copy the workflow into your repo:

GitHub

.github/workflows/crabd.yml

name: crab'd
on:
  issue_comment:
    types: [created]
  pull_request:
    types: [opened, reopened, ready_for_review]
  issues:
    types: [assigned, labeled]
  pull_request_review:
    types: [submitted]
  pull_request_review_comment:
    types: [created]

concurrency:
  group: crabd-${{ github.event.pull_request.number || github.event.issue.number || github.run_id }}
  cancel-in-progress: false

jobs:
  crabd:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      checks: read
      actions: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha || (github.event.issue.pull_request && format('refs/pull/{0}/head', github.event.issue.number)) || '' }}
          fetch-depth: 0
      - uses: louisescher/crabd@v0
        with:
          model: anthropic/claude-sonnet-4-6
          providers: anthropic
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

id-token: write lets crab’d post as the canonical crab’d[bot] via the token broker. You need to install the crab’d GitHub App on your repo for this to work. Prefer to hold your own key, or no App at all? See Operating crab’d.

Forgejo

.forgejo/workflows/crabd.yml

name: crab'd
on:
  issue_comment:
    types: [created]
  pull_request:
    types: [opened, reopened, ready_for_review]
  issues:
    types: [assigned, labeled]

jobs:
  crabd:
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha || (github.event.issue.pull_request && format('refs/pull/{0}/head', github.event.issue.number)) || '' }}
          fetch-depth: 0
      - uses: https://github.com/louisescher/crabd@v0
        with:
          forge: forgejo
          model: anthropic/claude-sonnet-4-6
          providers: anthropic
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          CRABD_FORGEJO_API_URL: ${{ github.server_url }}/api/v1
          CRABD_FORGEJO_TOKEN: ${{ secrets.CRABD_FORGEJO_TOKEN }}

Forgejo has no GitHub App equivalent, so crab’d posts as whatever bot account owns CRABD_FORGEJO_TOKEN. Create a dedicated bot user, give it repo access, and store its token as the CRABD_FORGEJO_TOKEN secret. See Operating crab’d.

Caution

Unlike GitHub’s ubuntu-latest, Forgejo has no universal runner label. runs-on: docker only works if your instance registered a runner with a docker label. Adjust runs-on to match a label your instance’s runners actually expose (check /{owner}/{repo}/settings/actions/runners).

Note

crab’d reads the model provider key straight from the environment (ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, …). Keep it in CI secrets.

Trigger your first run

Once the workflow is committed, try any of these:

• Mention: comment /crabd how does the auth middleware work? on an issue or PR.
• Review: open a pull request; crab’d reviews the diff automatically.
• Implement: assign an issue to crab’d (or label it) to have it open a PR.
• Review its work: review that pull request. On GitHub, crab’d answers every conversation and pushes a commit to the branch. On Forgejo, ask for the same thing with /crabd implement address the review.

crab’d posts a “working…” comment, then updates it in place with the result.

Steer a run

Anything you write after the mention is passed to the agent, so you can steer any mode:

/crabd please review. focus on the database migration and error handling

Next steps

• Configuration: every dial, layered config, and governance.
• Providers: use OpenAI, OpenRouter, or a local model.
• Modes: how mention, review, and implement behave.