Skip to content

Commit cd7f5e1

Browse files
ciemborciembor
committed
Document GitHub PR and CI operations
1 parent ce733ef commit cd7f5e1

9 files changed

Lines changed: 257 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@ DO NOT introduce Reek code smells in the code
44
AVOID generating code with code smells
55
In sandboxed or non-interactive shells, use repo entrypoints like `bin/bundle`,
66
`bin/rspec`, `bin/rake`, and `bin/quality` instead of plain `bundle exec ...`.
7+
For GitHub pull requests, merges, and Actions, read
8+
`docs/github-operations.md` and use `bin/gh`; do not depend on Homebrew being in
9+
`PATH`.
710

811
# OBEY A Philosophy of Software Design by John Ousterhout
912

‎bin/gh‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#!/bin/sh
2+
set -eu
3+
4+
if [ -n "${GH_BIN:-}" ]; then
5+
exec "$GH_BIN" "$@"
6+
fi
7+
8+
for candidate in /opt/homebrew/bin/gh /usr/local/bin/gh; do
9+
if [ -x "$candidate" ]; then
10+
exec "$candidate" "$@"
11+
fi
12+
done
13+
14+
printf '%s\n' \
15+
"GitHub CLI was not found. Install it with Homebrew or set GH_BIN." >&2
16+
exit 127

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ This directory is the canonical home for project documentation.
88
- [Monthly Snapshot Architecture](monthly-snapshot.md): monthly ranking flow, collaborator responsibilities, and architecture guardrails.
99
- [SQLite Data Ownership](data-ownership.md): table ownership, shared read dependencies, and schema change conventions.
1010
- [Development](development.md): local setup, quality checks, and day-to-day development commands.
11+
- [GitHub Operations](github-operations.md): persistent CLI authentication, pull request and Dependabot triage, merge policy, and GitHub Actions incident handling.
1112
- [Web App](web-app.md): local web server usage, public routes, and cache expectations.
1213
- [Crawl Jobs](crawl-jobs.md): monthly and package job behavior, production services, resume semantics, and server commands.
1314
- [Deployment](deployment.md): production topology, GitHub Actions deploy flow, and one-step rollback behavior.

‎docs/development.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,10 @@ In sandboxed or non-interactive shells, prefer repo entrypoints such as
4747
That keeps commands on the project's pinned Ruby even when the shell PATH falls
4848
back to `/usr/bin/bundle`.
4949

50+
Use `bin/gh` for GitHub CLI operations because Codex shells may omit Homebrew
51+
from `PATH`. Authentication, pull request merge policy, and Actions inspection
52+
are documented in [GitHub Operations](github-operations.md).
53+
5054
Mutation checks are available on demand through [Mutant](https://github.com/mbj/mutant):
5155

5256
```sh

‎docs/github-operations.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# GitHub operations
2+
3+
This repository uses GitHub CLI for pull request writes and GitHub Actions
4+
inspection. Use the repository entrypoint:
5+
6+
```sh
7+
bin/gh
8+
```
9+
10+
Do not depend on `gh` being present in the shell `PATH`. Codex shells may omit
11+
Homebrew paths even though GitHub CLI is installed at `/opt/homebrew/bin/gh`.
12+
`bin/gh` resolves the installed binary and supports an explicit `GH_BIN`
13+
override.
14+
15+
## Authentication and authorization
16+
17+
Authentication is stored by GitHub CLI in the operating system credential
18+
store and survives new Codex sessions. Verify it before a GitHub operation:
19+
20+
```sh
21+
bin/gh auth status
22+
bin/gh repo view --json nameWithOwner,viewerPermission
23+
```
24+
25+
The expected repository is `ciembor/polish-open-source`, and
26+
`viewerPermission` must be `WRITE`, `MAINTAIN`, or `ADMIN` for merge and branch
27+
write operations.
28+
29+
If authentication is missing or its scopes are insufficient, authenticate the
30+
operator account once:
31+
32+
```sh
33+
bin/gh auth login --hostname github.com --git-protocol ssh --web
34+
bin/gh auth refresh --hostname github.com --scopes repo,workflow,read:org
35+
```
36+
37+
Never copy or expose the GitHub CLI credential in repository files,
38+
`.env.local`, skill files, command arguments, or chat output. GitHub CLI owns
39+
its credential storage. The application's separately managed `GITHUB_TOKEN` in
40+
`.env.local` is runtime configuration and must not be reused as the CLI
41+
credential.
42+
43+
GitHub network commands may require sandbox approval. Request persistent
44+
approval for the narrow `bin/gh` command prefix when the execution environment
45+
supports persisted command rules.
46+
47+
## Pull request triage
48+
49+
List all open pull requests, including Dependabot and human-authored changes:
50+
51+
```sh
52+
bin/gh pr list --state open --limit 100 \
53+
--json number,title,author,isDraft,updatedAt,url
54+
```
55+
56+
Dependabot pull requests have `author.login` equal to `dependabot[bot]`. Do not
57+
filter the initial list by author because other contributors and automation
58+
must remain visible.
59+
60+
Inspect an individual pull request before changing it:
61+
62+
```sh
63+
bin/gh pr view PR_NUMBER \
64+
--json number,title,author,baseRefName,headRefName,isDraft,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,url
65+
bin/gh pr diff PR_NUMBER
66+
bin/gh pr checks PR_NUMBER
67+
```
68+
69+
For dependency updates, inspect the manifest and lockfile changes, the upstream
70+
release notes linked by Dependabot, and whether the update is major, minor, or
71+
patch. Treat major updates and security-relevant behavior changes as code
72+
changes requiring explicit compatibility review. Run the relevant local checks
73+
when the diff can affect runtime behavior.
74+
75+
## Merge policy
76+
77+
Merge only when the user requested that write action and all of these are true:
78+
79+
- the pull request targets `master` and is not a draft;
80+
- the diff is understood and contains no unrelated or suspicious changes;
81+
- required reviews are satisfied;
82+
- required checks have completed successfully;
83+
- GitHub reports the pull request as mergeable and not blocked;
84+
- any update-specific local verification has passed.
85+
86+
Use squash merge for this repository:
87+
88+
```sh
89+
bin/gh pr merge PR_NUMBER --squash --delete-branch
90+
```
91+
92+
If branch protection requires queued or delayed merging, use:
93+
94+
```sh
95+
bin/gh pr merge PR_NUMBER --squash --delete-branch --auto
96+
```
97+
98+
Do not bypass branch protection, use admin merge, dismiss reviews, or merge with
99+
failing or pending required checks unless the user explicitly requests the
100+
exception after the risk is stated. After merging, verify the resulting
101+
`master` workflow rather than assuming the pull request checks cover deploy.
102+
103+
## GitHub Actions inspection
104+
105+
Inspect pull request checks:
106+
107+
```sh
108+
bin/gh pr checks PR_NUMBER
109+
```
110+
111+
Inspect recent runs on any branch:
112+
113+
```sh
114+
bin/gh run list --workflow deploy.yml --limit 20
115+
bin/gh run view RUN_ID
116+
bin/gh run view RUN_ID --log-failed
117+
```
118+
119+
The workflow is named `CI and deploy`. Its required pre-deploy jobs are
120+
`Quality`, `Dependency security`, `CodeQL`, and `Container smoke`; `Deploy`
121+
starts only after all four succeed.
122+
123+
When CI fails:
124+
125+
1. Read the failed job and step logs before editing.
126+
2. Decide whether the failure is caused by the pull request, infrastructure, or
127+
an unrelated flaky dependency.
128+
3. For a code failure, reproduce it with the narrowest local command, implement
129+
the fix, then run the relevant tests and `bin/quality`.
130+
4. Commit and push the fix without skipping pre-commit hooks.
131+
5. Recheck the pull request checks and report any remaining failure.
132+
6. Rerun a failed job only when the failure is demonstrably transient:
133+
134+
```sh
135+
bin/gh run rerun RUN_ID --failed
136+
```
137+
138+
Do not rerun a deterministic code failure as a substitute for fixing it.
139+
140+
## Manual workflow actions
141+
142+
Normal deploys run after pushes to `master`. The documented one-step production
143+
rollback is the only routine manual workflow action:
144+
145+
```sh
146+
bin/gh workflow run deploy.yml --ref master -f action=rollback
147+
```
148+
149+
Follow [Deployment](deployment.md) and
150+
[Operations Runbook](operations-runbook.md) before dispatching or evaluating a
151+
deploy or rollback.
152+
153+
## Stable machine-readable output
154+
155+
Prefer `--json` plus `--jq` for decisions and summaries. Avoid scraping
156+
human-formatted tables. Useful repository identity checks are:
157+
158+
```sh
159+
bin/gh repo view --json nameWithOwner,defaultBranchRef,viewerPermission
160+
bin/gh api repos/ciembor/polish-open-source/branches/master/protection
161+
```
162+
163+
Branch protection can return `404` when it is not configured or when the
164+
authenticated account cannot read the setting. Distinguish those cases before
165+
making claims about merge requirements.

‎skills/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ for operational checklists, routing, and guardrails.
66

77
## Available Skills
88

9+
- [github-operations](github-operations/SKILL.md): inspect all pull requests,
10+
review Dependabot updates, merge eligible changes, and diagnose or repair
11+
GitHub Actions failures.
912
- [production-ops](production-ops/SKILL.md): production access, deploy or rollback,
1013
service triage, Podman containers, systemd units, `journalctl`, `/internal/jobs`,
1114
and production database inspection.

‎skills/github-operations/SKILL.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
name: github-operations
3+
description: Use for GitHub work in Polish Open Source Rank, including listing or inspecting pull requests from Dependabot or other authors, reviewing dependency updates, checking merge readiness, merging pull requests, reading GitHub Actions status and failed logs, rerunning transient failures, fixing CI failures, or dispatching the documented deploy or rollback workflow. Read docs/github-operations.md first and use bin/gh for every GitHub CLI command.
4+
---
5+
6+
# GitHub Operations
7+
8+
## Required context
9+
10+
Read [docs/github-operations.md](../../docs/github-operations.md) before issuing
11+
GitHub commands. For deploy or rollback work, also read
12+
[docs/deployment.md](../../docs/deployment.md) and
13+
[docs/operations-runbook.md](../../docs/operations-runbook.md).
14+
15+
Use `bin/gh`, not bare `gh`. The repository entrypoint resolves the Homebrew
16+
binary when the shell `PATH` does not include it.
17+
18+
## Workflow
19+
20+
1. Verify identity and permission:
21+
- `bin/gh auth status`
22+
- `bin/gh repo view --json nameWithOwner,viewerPermission`
23+
2. Inspect before writing:
24+
- list all open pull requests without filtering out human authors;
25+
- read PR metadata, diff, reviews, and checks;
26+
- inspect failed Actions logs before deciding on a fix or rerun.
27+
3. Apply the documented policy:
28+
- dependency PRs require manifest, lockfile, and release-note review;
29+
- merge only on an explicit user request and only when checks and reviews
30+
satisfy the repository rules;
31+
- use squash merge;
32+
- rerun only demonstrably transient CI failures.
33+
4. For code fixes:
34+
- reproduce locally;
35+
- make the narrowest coherent change;
36+
- run relevant tests and `bin/quality`;
37+
- commit and push without bypassing hooks;
38+
- verify the new GitHub checks.
39+
5. For deploy or rollback:
40+
- follow the production docs;
41+
- verify the resulting workflow and smoke checks.
42+
43+
## Guardrails
44+
45+
- Never expose or persist GitHub tokens in repository files or output.
46+
- Do not use admin merge, bypass protection, dismiss reviews, or merge with
47+
unresolved required checks unless the user explicitly accepts the stated
48+
risk.
49+
- Do not assume pull request checks prove the post-merge deploy succeeded.
50+
- Do not claim branch protection is absent solely because its API returned
51+
`404`.
52+
- Request persistent sandbox approval for the narrow `bin/gh` prefix when
53+
available.
54+
55+
## Output
56+
57+
Report the repository and PR or run identifiers inspected, the evidence used
58+
for the decision, every GitHub write performed, and any remaining failed,
59+
pending, external, or unverified check.

‎skills/github-operations/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "GitHub Operations"
3+
short_description: "Inspect PRs, merge safely, and fix CI"
4+
default_prompt: "Use $github-operations to inspect repository pull requests, handle Dependabot updates, merge eligible changes, and diagnose GitHub Actions failures."

‎skills/production-ops/SKILL.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ Read only the files needed for the task:
2525
manual crawl commands
2626
- `docs/operations-runbook.md`: restarts, alert checks, incident workflow, and
2727
backup restore procedure
28+
- `docs/github-operations.md`: GitHub CLI authentication, Actions inspection,
29+
workflow dispatch, and post-merge verification
2830
- `docs/publication.md`: publication and `publish_snapshot --rollback` tasks
2931
- `docs/performance.md`: latency, traffic spikes, and SLO-oriented triage
3032

0 commit comments

Comments
 (0)