GitHub Pull Request Workflow

Complete guide for managing the PR lifecycle. Each section shows the gh way first, then the git + curl fallback for machines without gh.

Diverged Branch Recovery

When git pull fails with "divergent branches" (local commits + remote commits both exist):

# Check what diverged
git log --oneline origin/main..HEAD   # local-only commits
git log --oneline HEAD..origin/main   # remote-only commits

# Stash any uncommitted changes first
git add -A && git stash

# Rebase local commits on top of remote (cleaner than merge)
git pull --rebase

# Restore stashed changes
git stash pop

Prefer --rebase over --no-rebase — keeps history linear. If stash pop conflicts, resolve manually.

Prerequisites

• Authenticated with GitHub (see github-auth skill)
• Inside a git repository with a GitHub remote

Quick Auth Detection

# Determine which method to use throughout this workflow
if command -v gh &>/dev/null && gh auth status &>/dev/null; then
  AUTH="gh"
else
  AUTH="git"
  # Ensure we have a token for API calls
  if [ -z "$GITHUB_TOKEN" ]; then
    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
      GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
    fi
  fi
fi
echo "Using: $AUTH"

Extracting Owner/Repo from the Git Remote

Many curl commands need owner/repo. Extract it from the git remote:

# Works for both HTTPS and SSH remote URLs
REMOTE_URL=$(git remote get-url origin)
OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/]||; s|\.git$||')
OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
REPO=$(echo "$OWNER_REPO" | cut -d/ -f2)
echo "Owner: $OWNER, Repo: $REPO"

1. Branch Creation

This part is pure git — identical either way:

# Make sure you're up to date
git fetch origin
git checkout main && git pull origin main

# Create and switch to a new branch
git checkout -b feat/add-user-authentication

Branch naming conventions:

• feat/description — new features
• fix/description — bug fixes
• refactor/description — code restructuring
• docs/description — documentation
• ci/description — CI/CD changes

2. Making Commits

Use the agent's file tools (write_file, patch) to make changes, then commit:

# Stage specific files
git add src/auth.py src/models/user.py tests/test_auth.py

# Commit with a conventional commit message
git commit -m "feat: add JWT-based user authentication

- Add login/register endpoints
- Add User model with password hashing
- Add auth middleware for protected routes
- Add unit tests for auth flow"

Commit message format (Conventional Commits):

type(scope): short description

Longer explanation if needed. Wrap at 72 characters.

Types: feat, fix, refactor, docs, test, ci, chore, perf

Auto-PR hooks and wrappers

If you want automatic PR creation for new feature branches, prefer a post-push hook or a wrapper command over a commit hook.

Why:

• commit hooks fire before the branch is on GitHub
• PR creation needs a pushed branch to be meaningful
• wrapper commands are easier to debug when gh pr create fails

See references/auto-pr-hooks.md for the branch-to-PR check and guardrails.

Push the Branch (same either way)

git push -u origin HEAD

Create the PR

If the repo supports auto-PR creation, this is where a post-push hook or wrapper may already have created the PR. Always check for an existing open PR before attempting a new one.

With gh:

gh pr create \
  --title "feat: add JWT-based user authentication" \
  --body "## Summary
- Adds login and register API endpoints
- JWT token generation and validation

## Test Plan
- [ ] Unit tests pass

Closes #42"

Options: --draft, --reviewer user1,user2, --label "enhancement", --base develop

Pitfall — requesting a reviewer can fail the create: @copilot is not always a valid GitHub login; in some repos/orgs Copilot review is configured through repo settings rather than a user-reviewer. A bad reviewer login makes gh pr create --reviewer fail outright. Create the PR first, then request the reviewer as a separate step so a lookup failure can't block the PR:

gh pr edit <PR_NUMBER> --add-reviewer <reviewer-login>

With git + curl:

BRANCH=$(git branch --show-current)

curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/$OWNER/$REPO/pulls \
  -d "{
    \"title\": \"feat: add JWT-based user authentication\",
    \"body\": \"## Summary\nAdds login and register API endpoints.\n\nCloses #42\",
    \"head\": \"$BRANCH\",
    \"base\": \"main\"
  }"

The response JSON includes the PR number — save it for later commands.

To create as a draft, add "draft": true to the JSON body.

Auto-PR hooks and wrappers

If you want automatic PR creation for new feature branches, prefer a post-push hook or a wrapper command over a commit hook.

Why:

• commit hooks fire before the branch is on GitHub
• PR creation needs a pushed branch to be meaningful
• wrapper commands are easier to debug when gh pr create fails

See references/auto-pr-hooks.md for the branch-to-PR check and guardrails.

4. Monitoring CI Status

Check CI Status

With gh:

# One-shot check
gh pr checks

# Watch until all checks finish (polls every 10s)
gh pr checks --watch

With git + curl:

# Get the latest commit SHA on the current branch
SHA=$(git rev-parse HEAD)

# Query the combined status
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/commits/$SHA/status \
  | python3 -c "
import sys, json
data = json.load(sys.stdin)
print(f\"Overall: {data['state']}\")
for s in data.get('statuses', []):
    print(f\"  {s['context']}: {s['state']} - {s.get('description', '')}\")"

# Also check GitHub Actions check runs (separate endpoint)
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/commits/$SHA/check-runs \
  | python3 -c "
import sys, json
data = json.load(sys.stdin)
for cr in data.get('check_runs', []):
    print(f\"  {cr['name']}: {cr['status']} / {cr['conclusion'] or 'pending'}\")"

Poll Until Complete (git + curl)

# Simple polling loop — check every 30 seconds, up to 10 minutes
SHA=$(git rev-parse HEAD)
for i in $(seq 1 20); do
  STATUS=$(curl -s \
    -H "Authorization: token $GITHUB_TOKEN" \
    https://api.github.com/repos/$OWNER/$REPO/commits/$SHA/status \
    | python3 -c "import sys,json; print(json.load(sys.stdin)['state'])")
  echo "Check $i: $STATUS"
  if [ "$STATUS" = "success" ] || [ "$STATUS" = "failure" ] || [ "$STATUS" = "error" ]; then
    break
  fi
  sleep 30
done

5. Auto-Fixing CI Failures

When CI fails, diagnose and fix. This loop works with either auth method.

Step 1: Get Failure Details

With gh:

# List recent workflow runs on this branch
gh run list --branch $(git branch --show-current) --limit 5

# View failed logs
gh run view <RUN_ID> --log-failed

With git + curl:

BRANCH=$(git branch --show-current)

# List workflow runs on this branch
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/actions/runs?branch=$BRANCH&per_page=5" \
  | python3 -c "
import sys, json
runs = json.load(sys.stdin)['workflow_runs']
for r in runs:
    print(f\"Run {r['id']}: {r['name']} - {r['conclusion'] or r['status']}\")"

# Get failed job logs (download as zip, extract, read)
RUN_ID=<run_id>
curl -s -L \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/actions/runs/$RUN_ID/logs \
  -o /tmp/ci-logs.zip
cd /tmp && unzip -o ci-logs.zip -d ci-logs && cat ci-logs/*.txt

Step 2: Fix and Push

After identifying the issue, use file tools (patch, write_file) to fix it:

git add <fixed_files>
git commit -m "fix: resolve CI failure in <check_name>"
git push

Step 3: Verify

Re-check CI status using the commands from Section 4 above.

Auto-Fix Loop Pattern

When asked to auto-fix CI, follow this loop:

1. Check CI status → identify failures
2. Read failure logs → understand the error
3. Use read_file + patch/write_file → fix the code
4. git add . && git commit -m "fix: ..." && git push
5. Wait for CI → re-check status
6. Repeat if still failing (up to 3 attempts, then ask the user)

6. Resolving PR Review Feedback

After a PR is opened and reviewed (either by Copilot, another reviewer, or Jason), the reviewer may leave inline comments visible under the PR's "Files changed" tab. Use this workflow to find, understand, and address them.

⚠️ Normal commits for review fixes — never amend+force-push after the PR is open

Once a PR is open and being reviewed:

• Each fix = a new plain commit (git commit -m "fix: ..." + git push)
• Amend + force-push rewrites history, blows away reviewer inline comment anchors (they go "Outdated" in GitHub), and makes it impossible for the reviewer to see what specifically changed between rounds
• Amend + force-push is only appropriate BEFORE the PR is open: squashing WIP commits into one clean feat commit, or rebasing onto main to drop already-merged commits

# ✅ Correct — PR is open, addressing a review comment:
git add <files>
git commit -m "[LKPR-N] fix: address reviewer comment — guard empty ids list"
git push

# ❌ Wrong — blows away comment anchors:
git commit --amend --no-edit
git push --force-with-lease

Step 1: Find Inline Comments

gh pr view does NOT show inline comments. Use the GitHub API directly:

PR_NUMBER=8
gh api repos/$OWNER/$REPO/pulls/$PR_NUMBER/comments \
  --jq '.[] | {path, body, line, commit_id}'

This returns each inline comment with the file path, body text, and line number. Review these to understand what changes are needed.

Step 2: Check What Type of Change is Needed

Inline comments generally fall into a few categories:

• Code change — fix a bug, refactor, add error handling, cache something
• Logging / error message — add log.warning() or log.exception() so silent failures become visible
• Frontend error handling — replace raw fetch() with an existing helper like api() that checks res.ok
• Architecture change — move computation from request-time to startup, cache results, etc.

Step 3: Make Changes on the Feature Branch

The PR already exists on a feature branch. Check out or stay on that branch:

# If you're already on it:
git status

# If you need to switch to it:
gh pr checkout $PR_NUMBER

Make the changes using patch or write_file, then:

git add <changed_files>
git commit -m "[TICKET-N] description: address PR review feedback"
git push

Commit message convention: use the ticket prefix (e.g. [LKPR-37]) followed by a description of what was addressed.

Step 4: Verify

Pushing auto-updates the existing PR — no need to create a new one. Verify with:

gh pr view $PR_NUMBER --json state,headRefOid

The reviewer's inline comments will show as "outdated" if the lines they commented on changed. New review comments may appear.

When Jason Is the Reviewer

Jason (Jessinra) reviews his own PRs and leaves inline comments. His feedback is always actionable. The pattern from experience:

• Jason may forget to publish his review. If he sends a message like "I forgot to publish" or "I have an update", the inline comments you already fetched may be stale. Re-fetch inline comments immediately via gh api repos/$OWNER/$REPO/pulls/$PR_NUMBER/comments — new ones will appear on the latest commit. The previous gh pr view and gh pr review calls don't capture inline comments, so always use the REST API for this.
• He may also add comments AFTER you've pushed a fix. If he says "I reviewed" and you already addressed the first batch, re-check for a new batch on your latest commit before calling it done.

• Silent exception handlers (except: return "unknown"): add log.exception(...) before the return
• Per-request subprocess calls: move to a module-level cache computed once at startup
• Raw `fetch()` in JS frontend: replace with the existing api() helper for proper HTTP error checks
• Frontend catch blocks: set a fallback value (e.g. "unknown") instead of empty catch(() => {})
• Unnecessary API endpoints: if a value is computed once at startup and only consumed by the app's own frontend, inject it server-side (template placeholder) instead of exposing an API endpoint. Jason explicitly prefers no extra endpoints — "remove API call, no need expose API call."
• These all fall under "don't spawn work per request" and "don't fail silently" — Jason considers both important.

7. Merging

With gh:

# Squash merge + delete branch (cleanest for feature branches)
gh pr merge --squash --delete-branch

# Enable auto-merge (merges when all checks pass)
gh pr merge --auto --squash --delete-branch

With git + curl:

PR_NUMBER=<number>

# Merge the PR via API (squash)
curl -s -X PUT \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/merge \
  -d "{
    \"merge_method\": \"squash\",
    \"commit_title\": \"feat: add user authentication (#$PR_NUMBER)\"
  }"

# Delete the remote branch after merge
BRANCH=$(git branch --show-current)
git push origin --delete $BRANCH

# Switch back to main locally
git checkout main && git pull origin main
git branch -d $BRANCH

Merge methods: "merge" (merge commit), "squash", "rebase"

Enable Auto-Merge (curl)

# Auto-merge requires the repo to have it enabled in settings.
# This uses the GraphQL API since REST doesn't support auto-merge.
PR_NODE_ID=$(curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['node_id'])")

curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/graphql \
  -d "{\"query\": \"mutation { enablePullRequestAutoMerge(input: {pullRequestId: \\\"$PR_NODE_ID\\\", mergeMethod: SQUASH}) { clientMutationId } }\"}"

8. Complete Workflow Example

# 1. Start from clean main
git checkout main && git pull origin main

# 2. Branch
git checkout -b fix/login-redirect-bug

# 3. (Agent makes code changes with file tools)

# 4. Commit
git add src/auth/login.py tests/test_login.py
git commit -m "fix: correct redirect URL after login

Preserves the ?next= parameter instead of always redirecting to /dashboard."

# 5. Push
git push -u origin HEAD

# 6. Create PR (picks gh or curl based on what's available)
# ... (see Section 3)

# 7. Monitor CI (see Section 4)

# 8. Merge when green (see Section 7)

Useful PR Commands Reference