DevelopmentSeed GitHub Playbook

Reusing Workflows

In this repository, we store reusable GitHub Actions workflows.

Recommended reading:

• Reusing workflows
• Creating starter workflows
• Using starter workflows

Claude PR Review

claude-pr-review.yml has Claude review every pull request for correctness and security issues, plus an over-engineering pass via the ponytail review skill. Findings land in one sticky PR comment that updates in place on every push.

Add it to a repo (or pick the "Claude PR Review" starter workflow under Actions → New workflow):

# .github/workflows/claude-review.yml
name: Claude Auto Review

on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
    paths-ignore:
      - '.github/workflows/**'

jobs:
  review:
    uses: developmentseed/.github/.github/workflows/claude-pr-review.yml@main
    permissions:
      contents: read
      pull-requests: write
      id-token: write
    secrets: inherit

All inputs are optional (pass under with:):

• ponytail (default true) — set false to drop the over-engineering pass.
• plugins / plugin_marketplaces — install your own Claude Code plugins (newline-separated name@marketplace and marketplace .git URLs). Caller-supplied marketplaces install unpinned from their default branch — only the built-in ponytail install is pinned to an exact commit.
• extra_instructions — text appended to the review prompt, e.g. to direct Claude to use a custom plugin's skill.
• show_cost (default true) — appends the estimated review cost (API-equivalent), duration, and turn count to the review comment; set false to hide.
• model — model ID for the review (e.g. claude-opus-4-8 for a more capable review). Empty uses Claude Code's default model (currently a Sonnet-tier model). Note: with subscription auth, bigger models consume the plan's usage quota faster.

secrets: inherit picks up the org-level CLAUDE_CODE_OAUTH_TOKEN secret, so most repos need no secret setup at all. To use a different token for one repo, either add a repo-level secret with the same name (it shadows the org secret), or map one explicitly instead of inheriting:

    secrets:
      CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.MY_OTHER_TOKEN }}

Creating the CLAUDE_CODE_OAUTH_TOKEN secret

1. On a machine with Claude Code installed and logged in with a Claude subscription (Pro/Max), run claude setup-token.
2. Approve the OAuth flow in the browser and copy the generated long-lived token (starts with sk-ant-oat01-).
3. Save it as an Actions secret named CLAUDE_CODE_OAUTH_TOKEN — at the org level (Settings → Secrets and variables → Actions → New organization secret) so every repo gets it via secrets: inherit, or per-repo. The token bills the subscription of whoever ran setup-token, so prefer a service/bot account for the org secret.

Multiple Pull Request templates

As of April 2022, Github doesn't support selecting from a list of PR templates (like it does with issues), but it will load different templates if specified through a query string. (?template=file.md)

A possible approach to multiple PR templates is to create a default template ( PULL_REQUEST_TEMPLATE.md - which is just a list of links) where you click preview and then can select your options. Example:

Code

## Available PR templates

<!--
  Github doesn't allow PR template selection the same way that it is possible with issues.
  Preview this and select the appropriate template:
-->

- [Version Release](?expand=1&template=version_release.md)
- _Alternatively delete and start empty_

All the other templates go inside the PULL_REQUEST_TEMPLATE directory. Each template should be a markdown file, whose filename you'll have to add to the list of links in the default template.

Here's a quick video demonstrating the flow.

Screen.Recording.2022-02-16.at.09.22.21.mov

Issue 1 Template

There's an Issue 1 template that can be used across any repositories in our Github account. Issue 1s are used to keep track of new projects and phases.

Here's how you can use it. In a repo, click Issues > New Issue > Issue 1