/github-pr-workflow

description: Full pull request lifecycle — create branches, commit changes, open PRs,
  monitor CI status, auto-fix failures, and merge. Works with gh CLI or falls back
  to git + GitHub REST API via curl.
version: 1.1.0
license: MIT
metadata:
  catalog:
    tags:
    - GitHub
    - Pull-Requests
    - CI/CD
    - Git
    - Automation
    - Merge
    related_skills:
    - github-auth
    - github-code-review

Kheish Compatibility

This skill is repo-local and stays inactive until explicitly activated.

When the original instructions refer to legacy tool names, use these Kheish mappings:

• `terminal` => `bash`
• `web_extract` => `web_fetch`, plus `web_search` when discovery is needed
• `search_files` => `grep_search` and `glob_search`
• `browser_*` tools require a browser-capable surfaced tool or MCP; if none is available, use the closest available surface and say so explicitly

When the instructions mention local helper files, resolve them from `${KHEISH_SKILL_DIR}`.

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`.

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"
elif [ -n "$GITHUB_TOKEN" ]; then
  AUTH="curl"
else
  AUTH="none"
fi
[ "$AUTH" = "none" ] && echo "Run 'gh auth login' or export GITHUB_TOKEN before PR API calls" && exit 1
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`

3. Pushing and Creating a PR

Push the Branch (same either way)

git push -u origin HEAD

Create the PR

**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`

**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.

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 --