.github/README.md

.github

Organization-level GitHub configuration for Sea Haven Industries.

What's in here

Reusable Workflows

.github/workflows/ci-python-sam.yaml — Reusable CI workflow for Python / SAM repos. Runs ruff check + ruff format --check, optional pytest, and optional sam validate --lint. Also usable for Python CDK repos by disabling SAM validate.

.github/workflows/ci-typescript-cdk.yaml — Reusable CI workflow for TypeScript / CDK repos. Runs npm ci + optional tsc --noEmit, optional ESLint, optional Jest, and optional cdk synth. Also supports Node.js SAM repos via an optional sam validate step.

.github/workflows/claude-code-review.yaml — Reusable PR review workflow powered by Claude Code. Individual repos call this via a thin wrapper workflow. Reviews for code correctness, security issues, and Sea Haven conventions (kebab-case, secrets placement, Lambda defaults).

.github/workflows/compliance-audit.yaml — Scheduled weekly audit (Mondays 10am ET) that checks all org repos for compliance with Sea Haven conventions. Creates GitHub issues on repos with violations. Can also be triggered manually via workflow_dispatch.

Scripts

scripts/rollout-review-workflow.sh — One-time script to push the thin PR review wrapper workflow to all org repos via the GitHub API. Creates a branch and PR on each repo.

Setup

1. Create a GitHub App

1. Go to Organization Settings > Developer settings > GitHub Apps > New GitHub App
2. Name it claude-code-ci (or similar)
3. Set Homepage URL to your org URL
4. Disable Webhook (uncheck "Active")
5. Set these Repository permissions:
   • Contents: Read and write
   • Issues: Read and write
   • Metadata: Read-only
   • Pull requests: Read and write
6. Set Where can this app be installed? to "Only on this account"
7. Click Create GitHub App
8. Note the App ID from the app's settings page
9. Under Private keys, click Generate a private key — save the .pem file

2. Install the App

1. From the app's settings page, click Install App
2. Select Sea-Haven-Industries
3. Choose All repositories

3. Add org-level secrets

Go to Organization Settings > Secrets and variables > Actions and add:

Secret	Value
ANTHROPIC_API_KEY	Your Claude API key
CLAUDE_CI_APP_ID	The App ID from step 1
CLAUDE_CI_APP_PRIVATE_KEY	The full contents of the .pem file from step 1

4. Add CI to a repo

Create .github/workflows/ci.yaml in the target repo. Examples:

Python SAM repo (e.g., afterhours-shift-manager, expense-approval-bot):

name: CI
on:
  pull_request:
    branches: [main]

jobs:
  ci:
    uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@main

TypeScript CDK repo (e.g., seahaven-door-unlock-api, seahaven-slack-bot):

name: CI
on:
  pull_request:
    branches: [main]

jobs:
  ci:
    uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@main

Node.js SAM repo (e.g., payments-dashboard):

name: CI
on:
  pull_request:
    branches: [main]

jobs:
  ci:
    uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@main
    with:
      run-typecheck: false
      run-cdk-synth: false
      run-sam-validate: true

Mixed stack (e.g., exec-aide — TypeScript CDK + Python Lambdas):

name: CI
on:
  pull_request:
    branches: [main]

jobs:
  python:
    uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@main
    with:
      source-dirs: "src"
      run-sam-validate: false
  typescript:
    uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@main

Enable optional steps as repos adopt them:

Input	Default	Turn on when...
run-tests	false	Repo has pytest tests or Jest tests
run-lint	false	Repo has an ESLint config
run-typecheck	true	Repo has tsconfig.json
run-cdk-synth	true	Repo is CDK-based
run-sam-validate	true (Python) / false (TS)	Repo has a SAM template

5. Roll out PR reviews to repos

./scripts/rollout-review-workflow.sh

This creates a PR on each repo adding the thin wrapper workflow. Review and merge them, then delete the add-claude-review branches.