AGENTS.md

1## Events Triggering Workflows
2 
3- Use `pull_request`, not `pull_request_target`. If you genuinely need secrets on a fork PR, never check out the PR's HEAD ref in the privileged job.
4- Be extremely careful with `workflow_run` for similar to `pull_request_target`.
5- When operating on `pull_request`, think if the workflow should use `concurrency` to cancel superseded runs.
6 
7## Workflow Permissions
8 
9Set `permissions: {}` at the workflow level and grant the minimum needed per-job.
10 
11```yaml
12permissions: {}
13
14jobs:
15  lint:
16    permissions:
17      contents: read
18    # ...
19  comment-on-pr:
20    permissions:
21      contents: read
22      pull-requests: write
23    # ...
24```
25 
26## Third-party GitHub Actions
27 
28Prefer GitHub-provided (`actions/*`) and Vercel-owned actions. For third-party actions:
29 
30- Don't include the third-party action if it doesn't provide much value, e.g. if a `pnpm`-installable tool can do the same job without much more code.
31- Pin to a full commit SHA, never a tag or branch. Include the tag as a trailing comment:
32 
33```yaml
34  uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
35```
36 
37- Before pinning, `git grep -n 'owner/repo@'` and reuse the SHA already in the repo if one exists. Otherwise look up the latest tag:
38 
39```sh
40  gh api repos/{owner}/{repo}/tags --jq '.[0:10] | .[] | {name, sha: .commit.sha}'
41```
42 
43- When using `actions/checkout`, pass `persist-credentials: false` unless the job actually needs to push or call the GitHub API as the checkout token.
44 
45## Installing CLIs from npm
46 
47- Use pnpm, not npm. Add the CLI to `devDependencies` (root `package.json` for CI-only tooling).
48- Use `pnpm add -D` over directly modifying `package.json`. Let pnpm figure out the latest version number.
49- `pnpm dlx` does not pin transitive deps; don't rely on it.
50- Bootstrap pnpm via corepack so it picks up `packageManager` from the root `package.json`.
51 
52## Downloading binaries (e.g. GitHub Releases)
53 
54- Hardcode the expected sha256 and validate before `chmod +x`.
55- Prefer official GitHub Releases assets over raw URLs.
56- Choose stable URLs. Use the `gh` CLI or GitHub API as needed to find releases.
57- Use `curl --retry 3` (or equivalent) so transient failures don't fail the workflow.
58 
59## Script injection
60 
61`${{ ... }}` is interpolated into the script before bash runs, so untrusted values (PR title, branch name, issue body) can break out and execute. Route them through an env var and quote on use:
62 
63```yaml
64- name: Check PR title
65  env:
66    TITLE: ${{ github.event.pull_request.title }}
67  run: |
68    set -euo pipefail
69    case "$TITLE" in
70      octocat*) echo "starts with octocat" ;;
71      *) exit 1 ;;
72    esac
73```
74 
75- Start multi-line `run:` blocks with `set -euo pipefail`.
76- Quote every `"$VAR"`.
77- Never `echo`/`printf` a secret. Use `::add-mask::` for dynamic secrets.
78- The same risk applies to `bash -c`, `sh -c`, and `child_process` invocations that build command strings.
79