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
2 changes: 1 addition & 1 deletion .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,5 +16,5 @@ Closes #

- [ ] `pnpm build`, `pnpm test`, `pnpm typecheck`, `pnpm lint:ci`, and `pnpm format:check` pass locally
- [ ] Tests added/updated where it makes sense
- [ ] No hand-edits to generated code (`packages/trueforge-sdk`, `.github/fern/openapi/openapi.json`, `docs/openapi.json`)
- [ ] No hand-edits to generated code (`packages/trueforge-sdk`, `.github/fern/openapi/openapi.json`, `docs/openapi.json`) — fork PRs omit SDK regen; maintainers regenerate after merge
- [ ] Docs / `.env.example` updated if configuration or behavior changed
43 changes: 35 additions & 8 deletions .github/workflows/generate-sdk.yaml
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
name: Generate SDK

# Regenerates the OpenAPI document and the SDK, and commits both to the branch.
# Fork PRs cannot receive that commit; main regenerates after merge.
on:
# Manual regen on main if the post-merge push job missed or failed.
workflow_dispatch:
push:
branches: [main]
# Only sources the document is built from; tests and metadata cannot change it.
Expand All @@ -24,6 +27,9 @@ concurrency:
group: generate-sdk-${{ github.head_ref || github.ref_name }}
cancel-in-progress: true

permissions:
contents: read

jobs:
generate:
name: Generate OpenAPI and TypeScript SDK
Expand All @@ -36,20 +42,22 @@ jobs:
if: >
github.actor != 'github-actions[bot]' &&
github.actor != 'trueforge-dev-bot[bot]'
permissions:
contents: write

steps:
- name: Create GitHub App token
id: app-token
if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository
if: >
github.event_name == 'push' ||
github.event_name == 'workflow_dispatch' ||
github.event.pull_request.head.repo.full_name == github.repository
uses: actions/create-github-app-token@v2
with:
app-id: ${{ secrets.TRUEFORGE_GENERATE_SDK_APP_ID }}
private-key: ${{ secrets.TRUEFORGE_GENERATE_SDK_APP_PRIVATE_KEY }}

# Branch tip, not the merge commit, so output can be pushed back; forks need the head repo named.
- name: Check out repository code
# Writable checkout: App token minted only for same-repo / push / dispatch.
- name: Check out branch
if: steps.app-token.outcome == 'success'
uses: actions/checkout@v4
with:
repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
Expand All @@ -58,6 +66,16 @@ jobs:
fetch-depth: 0
token: ${{ steps.app-token.outputs.token || github.token }}

# Forks skip the writable checkout above; without this the job has no code.
# Use base-repo pull refs (head.sha) — cloning the fork with GITHUB_TOKEN 403s.
- name: Check out pull request head
if: github.event_name == 'pull_request' && steps.app-token.outcome != 'success'
uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
fetch-depth: 0
persist-credentials: false

- name: Setup pnpm
uses: pnpm/action-setup@v4

Expand Down Expand Up @@ -105,11 +123,12 @@ jobs:
fi

# Same entrypoint as local `pnpm sdk:generate` (re-runs openapi:write; idempotent).
# App-token success = we can push; forks skip Fern so a flake cannot block the PR.
- name: Generate OpenAPI document and TypeScript SDK
if: steps.decide.outputs.needed == 'true'
if: steps.decide.outputs.needed == 'true' && steps.app-token.outcome == 'success'
run: pnpm sdk:generate

# Forks get a read-only token, so only the commit is skipped. TODO: an approval flow that can push to the fork.
# App-token success = writable head; forks cannot receive this commit.
- name: Commit generated output
if: steps.decide.outputs.needed == 'true' && steps.app-token.outcome == 'success'
# Passed as env, never interpolated into the script, so it cannot inject shell.
Expand Down Expand Up @@ -144,4 +163,12 @@ jobs:
- name: Report skipped commit on fork
if: steps.decide.outputs.needed == 'true' && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository
run: |
echo "::notice::Generation succeeded. The commit was skipped because pull requests from forks cannot push; a maintainer will regenerate after merge."
set -euo pipefail
{
echo "### Fork pull request"
echo
echo "OpenAPI/SDK commits are skipped on forks (GitHub Apps cannot push to the head repo)."
echo "Do not hand-edit \`packages/trueforge-sdk\` or the OpenAPI documents."
echo "After merge, **Generate SDK** on \`main\` regenerates both (or run it manually from Actions)."
} >> "$GITHUB_STEP_SUMMARY"
echo "::notice::Fork PR: OpenAPI/SDK will be regenerated on main after merge. Do not hand-edit generated files."
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ For security vulnerabilities, do **not** open a public issue — see [SECURITY.m

- **Node.js 22.13+** (see [`.nvmrc`](.nvmrc); required by pnpm 11.16)
- **pnpm** (version pinned via `packageManager` in [`package.json`](package.json); `corepack enable` handles it)
- **Docker** — only needed for Postgres/Redis dev infra, the smoke test, and SDK generation
- **Docker** — only needed for Postgres/Redis dev infra, the smoke test, and local SDK generation (maintainers). Fork contributors do not generate the SDK.

## Repository layout

Expand Down Expand Up @@ -202,7 +202,7 @@ Prettier and ESLint run as pre-commit hooks via husky + lint-staged.
## Pull requests

1. Fork (or branch) and create a topic branch: `git checkout -b my-fix`.
2. Make your change, with tests where it makes sense.
2. Make your change, with tests where it makes sense. Do not commit generated OpenAPI/SDK output (forks: source only; `main` regenerates after merge).
3. Make sure `pnpm build`, `pnpm test`, `pnpm typecheck`, `pnpm lint:ci`, and `pnpm format:check` pass — CI runs exactly these.
4. Keep PRs focused and reasonably small; describe **what** changed and **why** in the description.
5. Open the PR. A maintainer will review it; squash-merge is the norm.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ We compare TrueForge against Claude Managed Agents and deepagents on the same ta

## Contributing

We love contributions - bug reports, features, and docs fixes. See [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md).
We love contributions - bug reports, features, and docs fixes. See [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md). Fork PRs should change source only; maintainers regenerate the SDK after merge.

To report a security vulnerability, follow [SECURITY.md](SECURITY.md) instead of opening a public issue.

Expand Down
Loading