Skip to content

docs: add REST API and branch protection guidance #494

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mherod merged 2 commits into from
Mar 15, 2026
Merged

docs: add REST API and branch protection guidance #494

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e44c337
docs: add REST API and branch protection guidance
mherod Mar 15, 2026
988f8e0
Merge branch 'main' into docs/claude-md-rest-api-guidance
mherod Mar 15, 2026
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
32 changes: 28 additions & 4 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,12 +125,14 @@ return { data: [], ...(condition && { metrics: { ... } }) };
### Branch protection — `main` is fully protected

DO NOT run `git push origin main` directly. Branch protection requires all changes to
arrive via a PR with passing CI checks. Always push to a feature branch and open a PR:
arrive via a PR with passing CI checks. Always push to a feature branch and open a PR.
This applies to **all** changes — even in a solo/personal repo, branch protection rules
reject direct pushes. Always create a feature branch before committing:

```bash
git checkout -b chore/release-<version>
git push -u origin chore/release-<version>
gh pr create --title "chore: release <version>" ...
git checkout -b <type>/<slug>-<issue-number>
git push -u origin <type>/<slug>-<issue-number>
gh pr create --title "<type>(<scope>): description" ...
```

### Version bumping — avoid `pnpm version` / `npm version` in nvm environments
Expand Down Expand Up @@ -179,6 +181,28 @@ a stale global link exists. Remove it with `pnpm remove --global <package-name>`
- **Pre-existing infrastructure noise**: `Release to npm` OIDC failures when publishing
was already completed manually.

### GitHub API — prefer REST over GraphQL

Prefer `gh api` (REST) over `gh pr create`, `gh pr merge`, and other high-level `gh`
subcommands for PR and issue operations. The GraphQL API used by `gh pr` has stricter
rate limits; REST endpoints have separate, more generous limits.

```bash
# Create PR via REST (instead of gh pr create)
gh api repos/:owner/:repo/pulls \
-f title="feat: description" -f body="..." -f head="branch" -f base="main"

# Merge PR via REST (instead of gh pr merge)
gh api -X PUT repos/:owner/:repo/pulls/<number>/merge -f merge_method="squash"

# Update PR branch (rebase onto base)
gh api -X PUT repos/:owner/:repo/pulls/<number>/update-branch

# Check CI via REST
gh api "repos/:owner/:repo/commits/<sha>/check-runs" \
--jq '.check_runs[] | "\(.status)/\(.conclusion) \(.name)"'
```

### Session start — prior incomplete tasks

**DO** recreate prior-session incomplete tasks with `TaskCreate` at the start of each new
Expand Down
Loading