GitHub Operations
Deliver the requested GitHub state, not a successful-looking command. A 200, 201,
202, or 204 response is evidence that GitHub accepted a request; it is not proof
that every requested field changed, an invitation was accepted, an asynchronous job
finished, or the user's business outcome was achieved.
Route by operation
Read only the reference required for the task:
| Task |
Reference |
| Create, review, merge, close, compare, or converge PRs; retire remote PR branches |
references/pr_operations.md |
| Create, edit, search, transfer, close, or bulk-manage issues |
references/issue_operations.md |
| Inspect, clone, create, edit, rename, archive, transfer, change visibility, or delete repositories |
references/repository_operations.md |
| Inspect or change collaborators, teams, base permissions, member privileges, or organization 2FA |
references/organization_access_and_settings.md |
| Trigger, inspect, rerun, cancel, or purge Actions; manage secrets or variables |
references/workflow_operations.md |
| Use raw REST/GraphQL endpoints, pagination, rate limits, webhooks, or Enterprise hosts |
references/api_reference.md |
| Build scripts, retries, bulk operations, or machine-readable output |
references/best_practices.md |
For local Git recovery, dirty worktrees, bundles, or lost commits, use git-safety-net.
This skill owns GitHub-hosted state.
Universal operating contract
1. Classify the request before touching GitHub
- Answer, inspect, diagnose, or review: read-only. Do not create a PR, issue,
comment, invitation, workflow run, or setting change.
- Create, change, merge, close, grant, revoke, publish, or delete: the named
state change is authorized. Keep the target and blast radius inside that request.
- Destructive, public, credential-related, production-triggering, or externally
communicative: require the exact target, consequence, and recovery path. If the
user did not provide a material choice such as repository owner, visibility, or
message content, stop before the write.
Do not turn a read-only investigation into a mutation because the fix looks obvious.
Do not send a comment, review, issue, or invitation whose recipient or content was not
authorized in the current task.
2. Bind identity, host, and target
Before the first write, verify the active account and resolve a fully qualified target:
gh auth status --hostname HOST
gh api --hostname HOST user --jq '.login'
gh repo view HOST/OWNER/REPO \
--json nameWithOwner,visibility,isPrivate,viewerPermission,url
For github.com, OWNER/REPO is sufficient. Never use gh auth status --show-token
for routine diagnosis, and never print, paste, or log a token.
Before the first push to a remote in the current session, read its live visibility:
gh repo view OWNER/REPO \
--json nameWithOwner,visibility,isPrivate,stargazerCount,forkCount,url
3. Read current authority and preview the delta
Use GitHub-hosted state, not a stale local ref or remembered setting. Capture only the
fields required to prove the requested transition. Before a consequential write, make
this plan explicit:
Target: fully qualified repository, organization, PR, issue, run, or account
Current: authoritative fields and immutable IDs/SHAs
Requested: exact field or state transition
Blast radius: people, repositories, forks, runs, or public surfaces affected
Recovery: exact inverse operation or explicit “not recoverable”
Readback: independent GET/CLI query and expected result
If the user already authorized this exact consequence, execute it. Do not add a
ceremonial second confirmation. If target, scope, public exposure, deletion, recipient,
or recovery remains ambiguous, pause before the write.
4. Choose an interface whose input contract actually supports the change
Prefer, in order:
- a purpose-built
gh subcommand;
- a documented REST endpoint for one resource or authoritative readback;
- GraphQL when the required mutation/query is GraphQL-only or combines related data;
- the documented GitHub UI when the setting has no supported API input.
Response fields are not automatically writable fields. Before using PATCH, compare
the desired key against the operation's current request body parameters, not the
shape returned by GET. GitHub may ignore an unsupported key while still returning a
successful response. Do not switch API families merely to make the command run.
Use explicit methods with gh api. Adding -f or -F changes the default method to
POST; filtered GET requests must include -X GET.
5. Mutate once; do not retry ambiguity
- Pin repository, object number, branch, run ID, username, and expected SHA where the
operation supports it.
- Do not blindly retry non-idempotent writes such as comments, invitations, workflow
dispatches, releases, or PR/issue creation. After a timeout or 5xx, read back first to
determine whether the first request landed.
- For bulk changes, freeze and display the finite target list, then process one target
at a time with per-item results. Never pipe an unreviewed live query directly into a
destructive
xargs command.
- Do not bypass repository hooks, required checks, branch protections, signatures, or
visibility-consequence acknowledgements.
6. Verify through an independent readback
Run a fresh read that does not trust the mutation response or a cached local ref:
| Mutation |
Required acceptance evidence |
| PR merge/close/edit |
PR state plus accepted behavior on the fetched base when landing matters |
| Branch deletion |
Hosted branch/ref is absent; local remote-tracking cleanup is a separate check |
| Issue/comment/review |
Exact object exists once with the intended state/content |
| Repository create/edit/visibility |
Fully qualified repository readback matches owner, visibility, and requested fields |
| Collaborator/team permission |
Invitation state if pending, then effective permission; also identify remaining base/team grants when revoking |
| Organization setting |
A fresh organization/settings read returns every requested field; UI-only settings require UI readback plus any available API signal |
| 2FA requirement |
Preflight affected accounts, UI confirmation, API readback, then membership/outside-collaborator audit |
| Workflow dispatch/rerun/cancel |
The intended run ID reaches the expected state; command acceptance is not completion |
| Secret/variable change |
Metadata and consumer behavior, never secret value disclosure |
For asynchronous state, poll with a bounded deadline and report pending if the terminal
state is not observed. If readback differs, report failed/no-op or partially applied,
show the mismatched fields, and keep recovery available. Never say “done” from the write
receipt alone.
7. Report the business outcome
End with one of four honest states:
- changed and verified — requested state is independently observed;
- already satisfied — no write was necessary;
- pending — accepted but not yet terminal, with the next authoritative check;
- failed/no-op or partial — requested and observed states differ, with recovery and
unresolved risk.
High-impact boundaries
- Repository creation requires an explicit
OWNER/REPO and visibility. Never default
a generic example to --public; public exposure is a product decision.
- Repository visibility changes can expose code, Actions logs, artifacts, forks, and
history. Use
gh repo edit --visibility ... --accept-visibility-change-consequences
only after the consequences and exact repository are authorized, then read back.
- Merges, branch deletions, repository creation/deletion/transfer/visibility changes,
organization-wide permissions, 2FA enforcement, and secret rotation require their
operation-specific reference.
- PR and issue title formats are repository policy. Inspect templates, contribution
guidance, checks, or an accepted recent example; do not invent a universal JIRA prefix.
- Enterprise policy can override organization or repository controls. Preserve
HOST
explicitly and report when a lower layer cannot change the enforced state.
Safe read-only quick reference
gh pr list -R OWNER/REPO --state open --json number,title,state,url
gh pr view 123 -R OWNER/REPO --json number,title,state,headRefOid,baseRefOid,url
gh issue list -R OWNER/REPO --state open --json number,title,state,url
gh workflow list -R OWNER/REPO
gh run list -R OWNER/REPO --limit 20 \
--json databaseId,status,conclusion,headSha,url
gh api -X GET 'repos/OWNER/REPO/branches?per_page=100' --paginate --jq '.[].name'
Use --json/--jq for decisions. Human-formatted output is for reading, not parsing.
1---
2name: github-ops
3description: >-
4 Operates GitHub through gh CLI and the REST/GraphQL APIs with explicit target,
5 authorization, impact preview, and independent readback. Use for pull requests,
6 issues, Actions, repositories, collaborators, teams, organization member
7 privileges, base permissions, 2FA enforcement, repository settings, API
8 automation, parallel or superseded PR convergence, and public or enterprise
9 GitHub. Also use when a GitHub write returned success but the requested state did
10 not change, or when deciding whether a setting is writable through CLI, REST,
11 GraphQL, or only the GitHub UI.
12metadata:
13 source: https://skillmd.com/skills/gabrielmoreira/github-ops
14---
15
16# GitHub Operations
17
18Deliver the requested GitHub state, not a successful-looking command. A `200`, `201`,
19`202`, or `204` response is evidence that GitHub accepted a request; it is not proof
20that every requested field changed, an invitation was accepted, an asynchronous job
21finished, or the user's business outcome was achieved.
22
23## Route by operation
24
25Read only the reference required for the task:
26
27| Task | Reference |
28|---|---|
29| Create, review, merge, close, compare, or converge PRs; retire remote PR branches | [`references/pr_operations.md`](references/pr_operations.md) |
30| Create, edit, search, transfer, close, or bulk-manage issues | [`references/issue_operations.md`](references/issue_operations.md) |
31| Inspect, clone, create, edit, rename, archive, transfer, change visibility, or delete repositories | [`references/repository_operations.md`](references/repository_operations.md) |
32| Inspect or change collaborators, teams, base permissions, member privileges, or organization 2FA | [`references/organization_access_and_settings.md`](references/organization_access_and_settings.md) |
33| Trigger, inspect, rerun, cancel, or purge Actions; manage secrets or variables | [`references/workflow_operations.md`](references/workflow_operations.md) |
34| Use raw REST/GraphQL endpoints, pagination, rate limits, webhooks, or Enterprise hosts | [`references/api_reference.md`](references/api_reference.md) |
35| Build scripts, retries, bulk operations, or machine-readable output | [`references/best_practices.md`](references/best_practices.md) |
36
37For local Git recovery, dirty worktrees, bundles, or lost commits, use `git-safety-net`.
38This skill owns GitHub-hosted state.
39
40## Universal operating contract
41
42### 1. Classify the request before touching GitHub
43
44- **Answer, inspect, diagnose, or review:** read-only. Do not create a PR, issue,
45 comment, invitation, workflow run, or setting change.
46- **Create, change, merge, close, grant, revoke, publish, or delete:** the named
47 state change is authorized. Keep the target and blast radius inside that request.
48- **Destructive, public, credential-related, production-triggering, or externally
49 communicative:** require the exact target, consequence, and recovery path. If the
50 user did not provide a material choice such as repository owner, visibility, or
51 message content, stop before the write.
52
53Do not turn a read-only investigation into a mutation because the fix looks obvious.
54Do not send a comment, review, issue, or invitation whose recipient or content was not
55authorized in the current task.
56
57### 2. Bind identity, host, and target
58
59Before the first write, verify the active account and resolve a fully qualified target:
60
61```bash
62gh auth status --hostname HOST
63gh api --hostname HOST user --jq '.login'
64gh repo view HOST/OWNER/REPO \
65 --json nameWithOwner,visibility,isPrivate,viewerPermission,url
66```
67
68For `github.com`, `OWNER/REPO` is sufficient. Never use `gh auth status --show-token`
69for routine diagnosis, and never print, paste, or log a token.
70
71Before the first push to a remote in the current session, read its live visibility:
72
73```bash
74gh repo view OWNER/REPO \
75 --json nameWithOwner,visibility,isPrivate,stargazerCount,forkCount,url
76```
77
78### 3. Read current authority and preview the delta
79
80Use GitHub-hosted state, not a stale local ref or remembered setting. Capture only the
81fields required to prove the requested transition. Before a consequential write, make
82this plan explicit:
83
84```text
85Target: fully qualified repository, organization, PR, issue, run, or account
86Current: authoritative fields and immutable IDs/SHAs
87Requested: exact field or state transition
88Blast radius: people, repositories, forks, runs, or public surfaces affected
89Recovery: exact inverse operation or explicit “not recoverable”
90Readback: independent GET/CLI query and expected result
91```
92
93If the user already authorized this exact consequence, execute it. Do not add a
94ceremonial second confirmation. If target, scope, public exposure, deletion, recipient,
95or recovery remains ambiguous, pause before the write.
96
97### 4. Choose an interface whose input contract actually supports the change
98
99Prefer, in order:
100
1011. a purpose-built `gh` subcommand;
1022. a documented REST endpoint for one resource or authoritative readback;
1033. GraphQL when the required mutation/query is GraphQL-only or combines related data;
1044. the documented GitHub UI when the setting has no supported API input.
105
106Response fields are not automatically writable fields. Before using `PATCH`, compare
107the desired key against the operation's current **request body parameters**, not the
108shape returned by `GET`. GitHub may ignore an unsupported key while still returning a
109successful response. Do not switch API families merely to make the command run.
110
111Use explicit methods with `gh api`. Adding `-f` or `-F` changes the default method to
112`POST`; filtered GET requests must include `-X GET`.
113
114### 5. Mutate once; do not retry ambiguity
115
116- Pin repository, object number, branch, run ID, username, and expected SHA where the
117 operation supports it.
118- Do not blindly retry non-idempotent writes such as comments, invitations, workflow
119 dispatches, releases, or PR/issue creation. After a timeout or 5xx, read back first to
120 determine whether the first request landed.
121- For bulk changes, freeze and display the finite target list, then process one target
122 at a time with per-item results. Never pipe an unreviewed live query directly into a
123 destructive `xargs` command.
124- Do not bypass repository hooks, required checks, branch protections, signatures, or
125 visibility-consequence acknowledgements.
126
127### 6. Verify through an independent readback
128
129Run a fresh read that does not trust the mutation response or a cached local ref:
130
131| Mutation | Required acceptance evidence |
132|---|---|
133| PR merge/close/edit | PR state plus accepted behavior on the fetched base when landing matters |
134| Branch deletion | Hosted branch/ref is absent; local remote-tracking cleanup is a separate check |
135| Issue/comment/review | Exact object exists once with the intended state/content |
136| Repository create/edit/visibility | Fully qualified repository readback matches owner, visibility, and requested fields |
137| Collaborator/team permission | Invitation state if pending, then effective permission; also identify remaining base/team grants when revoking |
138| Organization setting | A fresh organization/settings read returns every requested field; UI-only settings require UI readback plus any available API signal |
139| 2FA requirement | Preflight affected accounts, UI confirmation, API readback, then membership/outside-collaborator audit |
140| Workflow dispatch/rerun/cancel | The intended run ID reaches the expected state; command acceptance is not completion |
141| Secret/variable change | Metadata and consumer behavior, never secret value disclosure |
142
143For asynchronous state, poll with a bounded deadline and report `pending` if the terminal
144state is not observed. If readback differs, report `failed/no-op` or `partially applied`,
145show the mismatched fields, and keep recovery available. Never say “done” from the write
146receipt alone.
147
148### 7. Report the business outcome
149
150End with one of four honest states:
151
152- **changed and verified** — requested state is independently observed;
153- **already satisfied** — no write was necessary;
154- **pending** — accepted but not yet terminal, with the next authoritative check;
155- **failed/no-op or partial** — requested and observed states differ, with recovery and
156 unresolved risk.
157
158## High-impact boundaries
159
160- Repository creation requires an explicit `OWNER/REPO` and visibility. Never default
161 a generic example to `--public`; public exposure is a product decision.
162- Repository visibility changes can expose code, Actions logs, artifacts, forks, and
163 history. Use `gh repo edit --visibility ... --accept-visibility-change-consequences`
164 only after the consequences and exact repository are authorized, then read back.
165- Merges, branch deletions, repository creation/deletion/transfer/visibility changes,
166 organization-wide permissions, 2FA enforcement, and secret rotation require their
167 operation-specific reference.
168- PR and issue title formats are repository policy. Inspect templates, contribution
169 guidance, checks, or an accepted recent example; do not invent a universal JIRA prefix.
170- Enterprise policy can override organization or repository controls. Preserve `HOST`
171 explicitly and report when a lower layer cannot change the enforced state.
172
173## Safe read-only quick reference
174
175```bash
176gh pr list -R OWNER/REPO --state open --json number,title,state,url
177gh pr view 123 -R OWNER/REPO --json number,title,state,headRefOid,baseRefOid,url
178gh issue list -R OWNER/REPO --state open --json number,title,state,url
179gh workflow list -R OWNER/REPO
180gh run list -R OWNER/REPO --limit 20 \
181 --json databaseId,status,conclusion,headSha,url
182gh api -X GET 'repos/OWNER/REPO/branches?per_page=100' --paginate --jq '.[].name'
183```
184
185Use `--json`/`--jq` for decisions. Human-formatted output is for reading, not parsing.