git-api-pr

When to Use This Skill

Context

• Repo: !git remote -v
• Default branch (configured): !git config --default '' --get init.defaultBranch
• Auth: !gh auth status
• Working dir: !pwd

Parameters

Parse these from $ARGUMENTS:

Execution

Execute this server-side PR creation workflow:

Step 1: Validate inputs

1. Parse file paths and flags from $ARGUMENTS
2. Verify --title is provided — error if missing
3. For each file path (unless --delete):
   • Verify the local file exists using Read tool
   • Resolve to a repo-relative path (strip leading ./ or working directory prefix)
4. Determine the repo from context ($REPO)
5. Determine base branch: use --base if provided, otherwise use default branch from context

Step 2: Resolve base branch state

# Get base branch SHA
BASE_SHA=$(gh api repos/$REPO/git/ref/heads/$BASE_BRANCH -q .object.sha)

# Get base tree SHA
BASE_TREE=$(gh api repos/$REPO/git/commits/$BASE_SHA -q .tree.sha)

If this fails, the base branch doesn't exist — report error and list available branches.

Step 3: Generate branch name (if --branch not provided)

Derive from the --title:

1. Take the subject part (after type(scope): )
2. Convert to kebab-case
3. Prefix with the commit type (e.g., fix/kebab-subject)
4. Example: "fix(api): handle null response" → fix/handle-null-response

Step 4: Create blobs for each file

For each file path:

# Base64-encode the file content and create a blob
BLOB_SHA=$(gh api repos/$REPO/git/blobs \
  -f content="$(base64 < "$FILE_PATH" | tr -d '\n')" \
  -f encoding=base64 \
  -q .sha)

Track each {path, blob_sha} pair for the tree creation in Step 5.

For --delete files, skip blob creation — these are handled differently in the tree.

Step 5: Create tree with all file changes

Build a tree JSON payload and create the tree:

# Write tree entries to a temp file
TREE_FILE=$(mktemp)

For each file to update/create, add a tree entry:

{"path": "relative/path/to/file", "mode": "100644", "type": "blob", "sha": "<blob_sha>"}

For each file to delete, add a tree entry:

{"path": "relative/path/to/file", "mode": "100644", "type": "blob", "sha": null}

Create the tree:

TREE_SHA=$(gh api repos/$REPO/git/trees \
  -f base_tree="$BASE_TREE" \
  --input "$TREE_FILE" \
  -q .sha)

Note: The --input file must contain the full JSON body with a tree array. Example:

{
  "base_tree": "<BASE_TREE>",
  "tree": [
    {"path": "src/config.ts", "mode": "100644", "type": "blob", "sha": "<blob1>"},
    {"path": "README.md", "mode": "100644", "type": "blob", "sha": "<blob2>"}
  ]
}

Step 6: Create commit

COMMIT_SHA=$(gh api repos/$REPO/git/commits \
  -f message="$TITLE" \
  -f tree="$TREE_SHA" \
  -f "parents[]=$BASE_SHA" \
  -q .sha)

Step 7: Create branch ref

gh api repos/$REPO/git/refs \
  -f ref="refs/heads/$BRANCH" \
  -f sha="$COMMIT_SHA"

If this fails with "Reference already exists", report the error and suggest using a different branch name.

Step 8: Create PR

When --body is provided, write it to a tempfile with the Write tool and pass --body-file. This sidesteps shell quoting entirely so backticks and code fences in the body render correctly. See the Body content rule in github-issue-writing for the canonical guidance.

# Write tool → "$TMP_BODY" (no shell escaping involved)
gh pr create \
  --repo "$REPO" \
  --head "$BRANCH" \
  --base "$BASE_BRANCH" \
  --title "$TITLE" \
  --body-file "$TMP_BODY"

When --body is unset, fall back to the trivial-body form --body "Created via API — no local git operations.".

Add --draft if the flag was provided.

Step 9: Report results

Print a summary:

PR created successfully (no local git changes):
  PR:     <url>
  Branch: <branch> → <base>
  Files:  <count> file(s) changed
  Commit: <sha>

Cleanup

Remove any temp files created during execution.

Error Recovery

Agentic Optimizations

See Also

• /git:commit — full local commit→push→PR workflow (use when you need pre-commit hooks, testing, or complex staging)
• gh-cli-agentic — GitHub CLI patterns for JSON output and API access
• git-branch-pr-workflow — branch management and PR workflow patterns