Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .agents/skills/github-prs/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,12 @@ description: How every agent verifies and attests locally (`make ci-local RAN="

Run the checks your change needs (lint, tests, build), then attest with `make ci-local RAN="…"` and merge right away. `make ci-local` runs nothing: it tells the PR you checked, and what. GitHub runs no verification on `main`, and on a PR only two small jobs that check the attestation. Stack PRs and merge each the moment it is attested; after the merge, check its staging deploy.

The rules on what may merge are in `AGENTS.md` ("Verifying", "Pull requests", "Environments: staging is always current"); the detail is in `docs/CI.md` ("What runs", "What to run", "Local verification", "Merging on local verification"). This skill is how you do it.
The rules on what may merge are in `AGENTS.md` ("Verifying", "Pull requests", "Environments: staging is always current"). This skill is how you do it.

## 1. Before every commit

- **Never skip the hooks.** `make hooks` installs the pre-push hook (`make check-fast`); when it fails, fix what it found and push again; never skip it.
- **Default: `make check-pr`.** It runs what the branch's changes need (the table is `docs/CI.md`, "What to run"), fails when the affected-package selection does not match the diff, and prints the `make ci-local RAN="…"` line to attest with. By hand: `make lint LINT_DIRS=<dirs>` and `make test TEST_PKGS=<pkgs>` for the Go packages it can affect (`scripts/affected.sh` prints them; `make check-fast` is the seconds-long pass), `make check-generated` for sqlc, templ or mock inputs, `make check-migrations` for a migration, `make deploy-check` for `deploy/`, `make actionlint` for workflows, `make release-smoke` for a Dockerfile or what it builds, `make ci` for a change to the tooling. In a Davit box, `make box-ci COMMIT=<sha>` runs check-generated, lint, build and test on exactly that commit and prints one PASS/FAIL line; never hand-write an inline `davit box run -- bash -lc "... rm ..."`. Tests only at the test boundaries (`AGENTS.md`, "Test boundaries"); never a test in `deploy/` or the UI.
- **Default: `make check-pr`.** It runs what the branch's changes need (the table is in `scripts/check-pr.sh`), fails when the affected-package selection does not match the diff, and prints the `make ci-local RAN="…"` line to attest with. By hand: `make lint LINT_DIRS=<dirs>` and `make test TEST_PKGS=<pkgs>` for the Go packages it can affect (`scripts/affected.sh` prints them; `make check-fast` is the seconds-long pass), `make check-generated` for sqlc, templ or mock inputs, `make check-migrations` for a migration, `make deploy-check` for `deploy/`, `make actionlint` for workflows, `make release-smoke` for a Dockerfile or what it builds, `make ci` for a change to the tooling. In a Davit box, `make box-ci COMMIT=<sha>` runs check-generated, lint, build and test on exactly that commit and prints one PASS/FAIL line; never hand-write an inline `davit box run -- bash -lc "... rm ..."`. Tests only at the test boundaries (`AGENTS.md`, "Test boundaries"); never a test in `deploy/` or the UI.
- A change adds no lint or format findings, warnings included.
- Add the paths you changed; never `git add -A` in an old worktree.

Expand Down Expand Up @@ -71,7 +71,7 @@ make pr-merge PR=<PR> ARGS=--dry-run # says what it would do
## 6. Checks that fail outside the code

- **Lost runner** ("lost communication with the server", "received a shutdown signal", "The operation was canceled.", a timeout with no log): `gh run rerun <run id> --failed`, once, by hand. Nothing re-runs it automatically.
- **Actions blocked** (billing or a spending limit: "The job was not started because…"): those jobs count as not run; `make pr-merge` merges on `local-ci` alone (`docs/CI.md`, "When Actions cannot run").
- **Actions blocked** (billing or a spending limit: "The job was not started because…"): those jobs count as not run; `make pr-merge` merges on `local-ci` alone.
- A real failure belongs to the PR's owner; the rest of the burst doesn't wait for it.
- One read per question (`gh pr checks <n>`, `gh run view <id> --json jobs`), never a polling loop.

Expand Down
8 changes: 4 additions & 4 deletions .claude/skills/github-prs/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,12 @@ description: How every agent verifies and attests locally (`make ci-local RAN="

Run the checks your change needs (lint, tests, build), then attest with `make ci-local RAN="…"` and merge right away. `make ci-local` runs nothing: it tells the PR you checked, and what. GitHub runs no verification on `main`, and on a PR only two small jobs that check the attestation. Stack PRs and merge each the moment it is attested; after the merge, check its staging deploy.

The rules on what may merge are in `AGENTS.md` ("Verifying", "Pull requests", "Environments: staging is always current"); the detail is in `docs/CI.md` ("What runs", "What to run", "Local verification", "Merging on local verification"). This skill is how you do it.
The rules on what may merge are in `AGENTS.md` ("Verifying", "Pull requests", "Environments: staging is always current"). This skill is how you do it.

## 1. Before every commit

- **Never skip the hooks.** `make hooks` installs the pre-push hook (`make check-fast`); when it fails, fix what it found and push again; never skip it.
- **Default: `make check-pr`.** It runs what the branch's changes need (the table is `docs/CI.md`, "What to run"), fails when the affected-package selection does not match the diff, and prints the `make ci-local RAN="…"` line to attest with. By hand: `make lint LINT_DIRS=<dirs>` and `make test TEST_PKGS=<pkgs>` for the Go packages it can affect (`scripts/affected.sh` prints them; `make check-fast` is the seconds-long pass), `make check-generated` for sqlc, templ or mock inputs, `make check-migrations` for a migration, `make deploy-check` for `deploy/`, `make actionlint` for workflows, `make release-smoke` for a Dockerfile or what it builds, `make ci` for a change to the tooling. In a Davit box, `make box-ci COMMIT=<sha>` runs check-generated, lint, build and test on exactly that commit and prints one PASS/FAIL line; never hand-write an inline `davit box run -- bash -lc "... rm ..."`. Tests only at the test boundaries (`AGENTS.md`, "Test boundaries"); never a test in `deploy/` or the UI.
- **Default: `make check-pr`.** It runs what the branch's changes need (the table is in `scripts/check-pr.sh`), fails when the affected-package selection does not match the diff, and prints the `make ci-local RAN="…"` line to attest with. By hand: `make lint LINT_DIRS=<dirs>` and `make test TEST_PKGS=<pkgs>` for the Go packages it can affect (`scripts/affected.sh` prints them; `make check-fast` is the seconds-long pass), `make check-generated` for sqlc, templ or mock inputs, `make check-migrations` for a migration, `make deploy-check` for `deploy/`, `make actionlint` for workflows, `make release-smoke` for a Dockerfile or what it builds, `make ci` for a change to the tooling. In a Davit box, `make box-ci COMMIT=<sha>` runs check-generated, lint, build and test on exactly that commit and prints one PASS/FAIL line; never hand-write an inline `davit box run -- bash -lc "... rm ..."`. Tests only at the test boundaries (`AGENTS.md`, "Test boundaries"); never a test in `deploy/` or the UI.
- A change adds no lint or format findings, warnings included.
- Add the paths you changed; never `git add -A` in an old worktree.

Expand Down Expand Up @@ -61,7 +61,7 @@ make pr-merge PR="<PR> [<PR> ...]" # merges every green PR now, reports the
make pr-merge PR=<PR> ARGS=--dry-run # says what it would do
```

- **Land inside the CI lock** on this machine: `make land PR=<PR>` in a clean worktree on its branch takes `/tmp/gfs-ci.lock`, rebases and pushes, runs `make ci-pg` inside that hold, attests, waits for the checks, merges with `make pr-merge` and releases the lock, so nothing lands between the rebase and the merge (docs/CI.md, "Merging on local verification").
- **Land inside the CI lock** on this machine: `make land PR=<PR>` in a clean worktree on its branch takes `/tmp/gfs-ci.lock`, rebases and pushes, runs `make ci-pg` inside that hold, attests, waits for the checks, merges with `make pr-merge` and releases the lock, so nothing lands between the rebase and the merge.
- **Green** means `local-ci` and the section attest the exact head, GitHub can merge it without conflicts, and the checks passed. It squash-merges with `--match-head-commit <head>`, so only the attested head lands. A head behind `main` is refused ("rebase onto origin/main and re-attest"): the merged tree must be the one you verified. Where Actions cannot run (no CI job ran, or GitHub never started them), it merges on `local-ci` alone and says so.
- Anything else (draft, unattested, pending, failing, conflicting, stacked) is reported with its next step; the script never waits. A head behind `main` or a conflict needs rebase, push, run what it needs, attest; after each merge in a burst, rebase the next PR.
- **After each merge, check its deploy** (a follow-up, never a gate; merge the next PR now): it prints `make pr-merge ARGS="--check-deploy <squash sha>"`. Run it once "Deploy staging" has run for that commit. Failed or refused: top priority, fix forward. Cancelled by a newer main deploy: `make pr-merge ARGS=--check-staging` checks main's head. A dry run (`RAILWAY_DEPLOY` not `true`) deployed nothing. With Actions off, it reads what Railway runs instead: deploy with `make railway-up PLATFORM_ENV=staging` from a clean checkout of the commit, which records it. After a burst, `ARGS=--then-check-staging` follows main's deploy (bounded).
Expand All @@ -73,7 +73,7 @@ make pr-merge PR=<PR> ARGS=--dry-run # says what it would do
## 6. Checks that fail outside the code

- **Lost runner** ("lost communication with the server", "received a shutdown signal", "The operation was canceled.", a timeout with no log): `gh run rerun <run id> --failed`, once, by hand. Nothing re-runs it automatically.
- **Actions blocked** (billing or a spending limit: "The job was not started because…"): those jobs count as not run; `make pr-merge` merges on `local-ci` alone (`docs/CI.md`, "When Actions cannot run").
- **Actions blocked** (billing or a spending limit: "The job was not started because…"): those jobs count as not run; `make pr-merge` merges on `local-ci` alone.
- A real failure belongs to the PR's owner; the rest of the burst doesn't wait for it.
- One read per question (`gh pr checks <n>`, `gh run view <id> --json jobs`), never a polling loop.

Expand Down
4 changes: 2 additions & 2 deletions .davit/setup.sh
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
#!/usr/bin/env bash
# The Davit project image (`davit box image build`): modules downloaded and
# the Go build, test and lint caches warmed for this tree, so a new box's
# first make lint / make test reuses them instead of compiling everything
# (docs/development.md, "Remote boxes"). Davit runs it from a copy, in the synced tree
# first make lint / make test reuses them instead of compiling everything.
# Davit runs it from a copy, in the synced tree
# (the working directory). Rebuild the image (`davit box image update`) when
# go.mod or tools/go.mod moves on: a stale cache still helps, it warms less.
set -euo pipefail
Expand Down
12 changes: 6 additions & 6 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ PUBLIC_URL=http://localhost:3000
# At least 32 characters. Generate one with: openssl rand -base64 32
AUTH_SECRET=dev-only-secret-change-me-0123456789abcdef
# While rotating: the old value(s), comma-separated, still accepted for
# AUTH_SECRET_GRACE (default: session lifetime, 30 days with 2FA). docs/secrets.md.
# AUTH_SECRET_GRACE (default: session lifetime, 30 days with 2FA). packages/secrets.
# AUTH_SECRET_PREVIOUS=
# A leaked value: never accepted again, only used to unwrap 2FA keys.
# AUTH_SECRET_REVOKED=
Expand All @@ -40,7 +40,7 @@ RESEND_API_KEY=
# example.com address is refused there).
FROM_EMAIL=noreply@example.com

# Google / Apple sign-in (optional, docs/sign-in.md). A
# Google / Apple sign-in (optional). A
# provider is on when its client id is set; then its credentials are required.
# Register <PUBLIC_URL>/auth/callback/google (or /apple) with the provider.
# GOOGLE_CLIENT_ID=xxxx.apps.googleusercontent.com
Expand All @@ -50,14 +50,14 @@ FROM_EMAIL=noreply@example.com
# APPLE_KEY_ID= live secret, rotates with the key
# APPLE_PRIVATE_KEY= live secret: the .p8 contents, \n for newlines

# Live secrets (docs/secrets.md): env (default, read once at boot) or doppler
# Live secrets (packages/secrets): env (default, read once at boot) or doppler
# (polled; RESEND_API_KEY rotates without a restart).
# SECRETS_PROVIDER=doppler
# DOPPLER_TOKEN=dp.st.dev.xxxx read-only service token for one config
# SECRETS_REFRESH_INTERVAL=60s
# SECRETS_MAX_STALENESS=15m

# Optional object storage + image uploads (docs/storage.md): off unless all
# Optional object storage + image uploads (packages/storage): off unless all
# four STORAGE_S3_* secrets are set (live secrets: from Doppler with
# SECRETS_PROVIDER=doppler). Region and path style are plain env.
# STORAGE_S3_ENDPOINT=http://127.0.0.1:9000
Expand All @@ -83,7 +83,7 @@ ADMIN_PUBLIC_URL=http://localhost:3001
# At least 32 characters and different from AUTH_SECRET: openssl rand -base64 32
ADMIN_AUTH_SECRET=dev-only-admin-secret-change-me-0123456789
# Rotating: ADMIN_AUTH_SECRET_PREVIOUS / ADMIN_AUTH_SECRET_REVOKED and
# ADMIN_AUTH_SECRET_GRACE work like the app's AUTH_SECRET_* (docs/secrets.md).
# ADMIN_AUTH_SECRET_GRACE work like the app's AUTH_SECRET_* (packages/secrets).
# Seeded (without a password) by `make admin-migrate`, which also sends its
# set-password link, again only once the last one has expired (in dev: open
# it from the log).
Expand All @@ -97,7 +97,7 @@ ADMIN_BOOTSTRAP_EMAIL=admin@example.com
# ADMIN_TRUSTED_ORIGINS=http://dev-box:3001
# ADMIN_DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/admin?sslmode=disable

# Backups (docs/backups.md). make db-backup encrypts with this key
# Backups (packages/backup). make db-backup encrypts with this key
# and stores in .backups/; set BACKUP_S3_* to use an S3-compatible bucket.
BACKUP_ENCRYPTION_KEY=dev-only-backup-key-change-me-0123456789abcdef
# BACKUP_S3_ENDPOINT=https://t3.storageapi.dev
Expand Down
2 changes: 1 addition & 1 deletion .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
> **Rules.** Before merge, run what this change needs on its exact head (docs/CI.md, "What to run"): for Go, `make lint test` scoped with `LINT_DIRS`/`TEST_PKGS` (`scripts/affected.sh` prints them) or `make check-fast`, plus the checks of what you touched. Then `make ci-local RAN="<what you ran>"` posts `local-ci` and fills "Local verification" with that statement and the head SHA. Never edit that section by hand. The `Local verification` check, `make pr-merge` and the staging gate refuse the PR while it is missing, names another head, or differs from what `local-ci` attested. A new push or rebase needs a new attestation. A reported failure (`FAILED=`) is final for that head: fix it in a new commit (docs/CI.md, "Local verification").
> **Rules.** Before merge, run what this change needs on its exact head (`make check-pr` runs it): for Go, `make lint test` scoped with `LINT_DIRS`/`TEST_PKGS` (`scripts/affected.sh` prints them) or `make check-fast`, plus the checks of what you touched. Then `make ci-local RAN="<what you ran>"` posts `local-ci` and fills "Local verification" with that statement and the head SHA. Never edit that section by hand. The `Local verification` check, `make pr-merge` and the staging gate refuse the PR while it is missing, names another head, or differs from what `local-ci` attested. A new push or rebase needs a new attestation. A reported failure (`FAILED=`) is final for that head: fix it in a new commit.

## Problem

Expand Down
2 changes: 1 addition & 1 deletion .github/scripts/deploy-railway.sh
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@
# it: what the workflows do until RAILWAY_DEPLOY is true
#
# Never pass a variable named RAILWAY_ENV: it switches the Railway CLI to
# Railway's internal API (docs/railway-go-iac-issues.md).
# Railway's internal API.
set -eu

usage="usage: sh .github/scripts/deploy-railway.sh <environment> <sha>"
Expand Down
14 changes: 5 additions & 9 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
# Pull requests only: the agent runs what its change needs before merge and
# attests it with `make ci-local RAN="<what you ran>"` (docs/CI.md, "Local
# verification"), and main runs no CI. This keeps the two small checks the
# attests it with `make ci-local RAN="<what you ran>"`, and main runs no CI. This keeps the two small checks the
# main ruleset requires: the secret scan, and the check that make ci-local's
# attestation holds for the head. A push to main is gated separately: Deploy
# staging deploys only a commit make ci-local attested (deploy-staging.yml).
#
# Trusted code only (docs/CI.md, "What runs"): pull_request_target runs this
# Trusted code only: pull_request_target runs this
# file and checks out the code as they are on the base branch, never the pull
# request's. The jobs read the head as data, through the API and git's
# objects, and never run it, so a branch or a fork that rewrites
Expand Down Expand Up @@ -35,8 +34,7 @@ concurrency:
on:
pull_request_target:
# Edits only: make ci-local posts local-ci, then fills the PR body, and
# that edit starts the run that checks both (docs/CI.md, "Local
# verification"). A push or a new PR starts nothing, and an edit before
# that edit starts the run that checks both. A push or a new PR starts nothing, and an edit before
# make ci-local claims the head runs Local verification under another
# name, so until it attests the required checks wait as "Expected",
# never red; a job skipped by `if` would count as passed.
Expand All @@ -45,8 +43,7 @@ on:
jobs:
secrets:
name: Secret scan
# The pull request's changed files, docs included (docs/CI.md, "Secret
# scan"), read from the head's objects and scanned with the base's
# The pull request's changed files, docs included, read from the head's objects and scanned with the base's
# scanner and policy (.gitleaks.toml, .gitleaksignore); a head that edits
# that policy fails for review. It does not depend on the agent's machine.
runs-on: ${{ fromJSON(vars.CI_RUNNER || '"ubuntu-latest"') }}
Expand Down Expand Up @@ -102,8 +99,7 @@ jobs:
run: go run ./scripts/cilocal check --claim

local:
# The agent ran the PR's checks on its machine (docs/CI.md, "Local
# verification"). For a claimed head this is the required check, and
# The agent ran the PR's checks on its machine. For a claimed head this is the required check, and
# fails unless the local-ci status on the head and the PR body's section
# attest them. For any other it passes under another name and posts
# nothing the ruleset reads.
Expand Down
4 changes: 2 additions & 2 deletions .golangci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -49,10 +49,10 @@ linters:
# route's policy. See exclusions for where each is allowed.
- pattern: ^auth\.UserFrom$
pkg: ^github\.com/jayleaton/go-fast-stack/packages/auth$
msg: "the caller comes from the route's access policy: register the route with api.Route / the UI's page or action and use the caller it passes (AGENTS.md \"Architecture\", docs/route-access.md)"
msg: "the caller comes from the route's access policy: register the route with api.Route / the UI's page or action and use the caller it passes (AGENTS.md \"Architecture\", apps/web/internal/access)"
- pattern: ^access\.Gate\.Admit$
pkg: ^github\.com/jayleaton/go-fast-stack/apps/(web|admin)/internal/access$
msg: "only the central route handler admits a request: register the route with api.Route / the UI's page or action and its access.Policy (docs/route-access.md)"
msg: "only the central route handler admits a request: register the route with api.Route / the UI's page or action and its access.Policy (apps/web/internal/access)"
# UIs only (see exclusions): a page never links to, fetches or posts
# to the JSON API; forms post to the UI's own action routes.
- pattern: ^config\.APIRoutes$
Expand Down
Loading
Loading