GitHub CLI & Git Workflow Runbook
Follow these structured procedures and guidelines when working with Git branches, commits, pull requests, and GitHub CLI (gh) commands.
1. GitHub CLI (gh) Guidelines for Windows
[!IMPORTANT] Always use
--body-file(or-F) when passing markdown bodies toghCLI commands on Windows. Never use inline strings (--bodyor-b) for multiline markdown, PR descriptions, issue bodies, or release notes. PowerShell and Windows CMD shell quoting frequently cause broken newlines, mangled quotes, and unwanted character escapes.
Creating a Pull Request with gh pr create
Write the PR description to a file (e.g., in a temporary or scratch directory):
# Example: write PR body to a temp markdown file @' ## Context & Motivation Brief description of the problem, background, and why this change was made. ## Key Changes & Impact - Key change 1 - Key change 2 ## Testing & Verification - Ran automated tests via `dotnet run` - Verified build with Visual Studio 2026 MSBuild '@ | Set-Content -Path ./pr_body.md -Encoding utf8Execute
gh pr createusing--body-file:gh pr create --title "feat: descriptive title" --body-file ./pr_body.md --base mainClean up the temporary file:
Remove-Item -Path ./pr_body.md -ErrorAction SilentlyContinue
Creating or Editing Issues with gh
Similarly, always write issue bodies to a file and supply --body-file:
gh issue create --title "bug: descriptive title" --body-file ./issue_body.md
2. Commit Message & PR Title Conventions
- Use the Conventional Commits standard.
- Format:
<type>(<optional-scope>): <short summary>feat: A new featurefix: A bug fixdocs: Documentation changes onlyrefactor: Code changes that neither fix a bug nor add a featureperf: Performance improvementstest: Adding or correcting testschore: Maintenance tasks, dependency updates, build tooling
- PR titles must follow conventional commit naming.
- PR descriptions must include Context, Motivation, and Impact, referencing any related issues (
Fixes #123,Resolves #456).
3. Branching & Push Workflow
- Ensure changes are committed with conventional messages.
- Push branch to remote:
git push -u origin <branch-name> - Open pull request using
gh pr create --body-file <path>.