gh-pr-release-flow/README.md

gh-pr-release-flow

A lightweight skill for GitHub repos that block direct pushes to main, require pull requests, and expect release work to happen after merge.

This repo exists to encode one practical workflow:

PR first, release after merge.

Why this exists

A lot of GitHub workflow pain is repetitive, not interesting:

• pushing to main and getting rejected by repo rules
• assuming approvals = 0 means direct push is allowed
• discussing release updates before the relevant changes are merged
• forgetting to check whether package.json, git tags, and GitHub releases are aligned

This skill turns those repeated mistakes into a default operating habit.

What this skill helps with

• detect when a repo is effectively PR-only
• switch from local commits to branch + PR flow quickly
• decide whether release work must wait until after merge
• keep version / tag / release state from drifting apart
• stop repeating the same protected-branch mistakes

When to use it

Use this skill when you are working in a GitHub repo and any of these are true:

• direct push to main may be blocked
• the repo uses branch protection / PR-only rules
• you need to open a PR after local work
• you need to decide whether a release should happen now or wait for merge
• you keep re-learning the same GitHub publishing flow from scratch

Default policy

If repo rules are unknown, prefer this order:

1. local commit
2. branch
3. push branch
4. PR
5. merge
6. release

In short: PR first, release after merge.

Example situations

Example 1: docs change in a protected repo

You update README locally, commit, try to push, and GitHub rejects direct push to main.

Correct move:

• keep the local commit
• create a branch
• push the branch
• open a PR

Example 2: user says “update the release”

Before touching the release:

• check whether the intended changes are already merged
• inspect current version, tags, and releases
• if changes are still only in an open PR, wait or explicitly create a prerelease/draft

Example 3: approvals are set to 0

That still does not prove direct push is allowed. Branch protection may still require PRs.

What this skill does not try to be

This is not a general GitHub encyclopedia. It is intentionally narrow:

• protected branch / PR-first repos
• release-after-merge workflow
• practical decision rules

Repo contents

• SKILL.md — the actual skill instructions for agent use
• README.md — human-readable overview and examples

Suggested next improvements

Future iterations can add:

• PR body examples
• release notes examples
• repo-rule detection checklist
• examples for patch vs minor release decisions

License

MIT