/opening-prs

name: opening-prs
description: Open a GitHub PR via API as a flowing graph — branch + push + create_pr + mergeable poll, with structural protection against pushing to main/master/etc. Use when a Claude Code or Claude.ai container needs to land changes on GitHub via the API (no git CLI required) and the prose "create branch, push, open PR, wait for mergeable" workflow keeps drifting under context pressure.
metadata:
  version: 0.1.0
  requires: flowing

Opening PRs

A `flowing` graph that turns the imperative "create branch, push files, open a PR, poll mergeable_state" workflow into a structural DAG. The "NEVER push directly to main" rule is encoded as a `validate=` gate that physically can't be skipped.

from opening_prs import open_pr

result = open_pr(
    repo="owner/repo",
    branch_name="feat/cool-thing",
    title="Add cool thing",
    body="## Summary\n\n...",
    files=[
        ("src/cool.py", "<file content>"),
        ("docs/cool.md", "<file content>"),
    ],
    base="main",  # default; protected names are also rejected
)

print(result["pr_url"])             # https://github.com/.../pull/N
print(result["mergeable_state"])    # clean | dirty | unstable | behind | blocked

What this fixes

The `gh pr create` workflow (or hand-rolled API calls) has five steps in prose form:

1. Determine the branch name 2. Get the base branch's HEAD SHA 3. Create the branch 4. Push files to the branch 5. Create the PR 6. Poll `mergeable_state` until GitHub finishes computing it

Each step has known failure modes:

• **Step 1**: Accidentally pushing to `main` — the diagnosed pattern that

motivated github-procedures §6 in the first place.

• **Step 6**: GitHub returns `mergeable_state: null` immediately after

creation. Need to poll. "Wait a few seconds and check" is prose, not a procedure — so it gets skipped under context pressure.

This skill encodes both as flowing primitives:

determine_branch ──▶ guard ──▶ get_base_head ──▶ create_branch
                      │                              │
                      │                              ▼
                      │                        push_files
                      │                              │
                      │                              ▼
                      │                         create_pr
                      │                          /        \
                      │                         ▼          ▼
                      │                  wait_mergeable  present_pr [terminal]
                      │
                      └─ validate=must_not_be_base_branch

• **`validate=must_not_be_base_branch`** rejects `branch_name in

{"main", "master", "trunk", "production", "prod"}` — case-insensitive — and the configured `base` itself. The body of `create_branch` never fires for a protected name. No GitHub API call happens for an invalid branch name.

• **`retry_until=lambda r: r["mergeable_state"] in SETTLED_STATES`**

consumes the retry budget while GitHub computes the merge result. `unknown` and `null` keep polling; settled states (`clean`, `dirty`, `unstable`, `behind`, `blocked`) stop. Exhaustion is soft: the PR is still presented with the last observed state.

Auth

Requires `GH_TOKEN` (or `GITHUB_TOKEN`) in the environment. Classic PAT or fine-grained PAT with `repo` scope.

import os
os.environ["GH_TOKEN"] = "ghp_..."   # or load from a .env file

The skill sends `User-Agent: opening-prs` on every API call. (GitHub returns 401 "Bad credentials" without a UA, regardless of token validity. Common trap.)

Result shape

{
    "pr_url": "https://github.com/owner/repo/pull/N",
    "pr_number": 42,
    "pr_state": "open",
    "branch": "feat/cool-thing",
    "base": "main",
    "head_sha": "abc123...",
    "mergeable_state": "clean",
    "files_pushed": ["src/cool.py", "docs/cool.md"],
    "detached_failures": [],
}

Raises `RuntimeError` only if the main DAG fails (validate, branch creation, file push, or PR creation). Mergeable polling exhaustion is a soft failure — the PR exists, the field just isn't computed yet.

Tuning the mergeable poll

open_pr(
    ...,
    mergeable_poll_retries=8,         # default 8
    mergeable_poll_base_ms=2000,      # default 2s
    mergeable_poll_max_ms=8000,       # default 8s (cap on exponential backoff)
)

When NOT to use

• Pushing many large files (the GitHub Contents API is one-file-per-PUT

with base64 encoding — slow above ~10 files). Use `git push` if you have the CLI.

• Needing to amend commits or rewrite history. This skill creates one

commit per file via the contents API.

• Anything involving force-push, branch deletion, or PR review-state

manipulation. Out of scope; use a different tool.

See also

• `flowing` — the DAG runner this skill is built on
• `closing-issues` — the symmetric "close + synthesize" flow
• The `accessing-github-repos` skill for byte-layer GitHub access patterns