github-pr-workflow

GitHub Pull Request Workflow

Complete guide for managing the PR lifecycle. All sections show the gh way — for git + curl fallbacks, see references/curl-fallback.md.

Diverged Branch Recovery

git log --oneline origin/main..HEAD   # local-only commits
git log --oneline HEAD..origin/main   # remote-only commits
git add -A && git stash
git pull --rebase
git stash pop

Prefer --rebase over --no-rebase — keeps history linear.

Prerequisites

Quick Auth Detection

if command -v gh &>/dev/null && gh auth status &>/dev/null; then
  AUTH="gh"
else
  AUTH="git"
fi
echo "Using: $AUTH"

Extracting Owner/Repo

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)

---

1. Branch Creation

git fetch origin
git checkout main && git pull origin main
git checkout -b feat/add-user-authentication

Branch naming: feat/, fix/, refactor/, docs/, ci/ + description.

2. Making Commits

git add src/auth.py src/models/user.py
git commit -m "feat: add JWT-based user authentication

- Add login/register endpoints
- Add unit tests for auth flow"

Commit format: type(scope): short description. Types: feat, fix, refactor, docs, test, ci, chore, perf.

3. Pushing and Opening a PR

Push

git push -u origin HEAD

Create the PR

gh pr create \
  --title "feat: add JWT-based user authentication" \
  --body "## Summary\nCloses #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. Create the PR first, then add reviewer separately:

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

For curl fallback, see references/curl-fallback.md.

4. Monitoring CI Status