Guide
Control Write Safety
Gate dangerous operations with human approval policies.
Write operations like merging a PR or closing an issue can have irreversible consequences. The SDK provides an approval layer that intercepts mutations before they execute.
AI assistant prompt (write safety)
Prompt
Configure @github-tools/sdk write safety in this project: use requireApproval on createGithubTools or createGithubAgent so destructive GitHub actions stay human-gated where appropriate. Follow https://github-tools.com/guide/approval-control and cross-check the PAT with https://github-tools.com/guide/token-permissions. Note: requireApproval is not enforced by createDurableGithubAgent today — use non-durable agents or app-level guards for durable paths.
Require approval for all writes
By default, every write operation requires explicit approval. You don't need to pass any extra option:
default-approval.ts
import { createGithubTools } from '@github-tools/sdk'
const tools = createGithubTools({
})
Disable approval in trusted environments
In CI pipelines or automated workflows where human review happens elsewhere (e.g. PR-based), you can disable approval entirely:
ci-pipeline.ts
import { createGithubTools } from '@github-tools/sdk'
const tools = createGithubTools({
requireApproval: false,
})
Configure approval per operation
For nuanced policies, enable approval selectively. This example approves destructive actions but allows comments freely:
selective-approval.ts
import { createGithubTools } from '@github-tools/sdk'
const tools = createGithubTools({
requireApproval: {
createBranch: false,
forkRepository: true,
createRepository: true,
mergePullRequest: true,
createOrUpdateFile: true,
closeIssue: true,
createPullRequest: false,
addPullRequestComment: false,
createIssue: false,
addIssueComment: false,
},
})
Assess risk by operation
| Operation | Risk | Suggested policy |
|---|---|---|
createRepository | High | Always require approval |
forkRepository | High | Always require approval |
createOrUpdateFile | High | Always require approval |
mergePullRequest | High | Always require approval |
closeIssue | Medium | Require in production repos |
createPullRequest | Medium | Optional in trusted CI |
createBranch | Low | Usually skip |
addPullRequestComment | Low | Usually skip |
createPullRequestReview | Medium | Require in production repos |
addIssueComment | Low | Usually skip |
addLabels | Low | Usually skip |
removeLabel | Low | Usually skip |
deleteGist | High | Always require approval |
createGist | Medium | Optional in trusted CI |
updateGist | Medium | Require in production |
createGistComment | Low | Usually skip |
triggerWorkflow | High | Always require approval |
cancelWorkflowRun | High | Always require approval |
rerunWorkflowRun | Medium | Require in production repos |
Override approval per tool
You can also set needsApproval via the overrides option, which supports all AI SDK tool properties:
override-approval.ts
createGithubTools({
overrides: {
addIssueComment: { needsApproval: false },
mergePullRequest: { needsApproval: true },
},
})
When both requireApproval and overrides set needsApproval for the same tool, the overrides value wins (it is applied last).
Approval is one safety layer, not the only one. Combine it with least-privilege token scopes and narrow presets.