GitHub Workflows & Collaboration

7.2.1Definition

A GitHub workflow (or equivalent on GitLab/Bitbucket) is the collaborative process a team follows around Git — pull requests, code review, branch protection rules, and automated checks — that determine how a change actually reaches the main codebase, beyond Git's raw mechanics (7.1).

7.2.2Why It Exists

Git alone provides no review gate — any commit can be pushed to any branch by anyone with access. Collaboration workflows exist to insert human review and automated verification (7.5) between "a change exists" and "a change is part of the shipped product," catching mistakes before they reach users rather than after.

7.2.3Core Workflow Elements

• Pull/merge requests — a proposed change presented for review before merging, showing the full diff and discussion thread.
• Code review — at least one other person examines the change for correctness, style, and design before approval.
• Branch protection — rules preventing direct pushes to main and requiring passing checks (7.5) and approvals before merge.
• Issue tracking — linking a change back to the problem or feature request it addresses, preserving the "why" alongside the "what."

7.2.4Common Mistakes

• Rubber-stamp reviews approved without genuinely reading the diff, defeating the entire purpose of the review gate.
• Enormous pull requests bundling many unrelated changes, making thorough review practically impossible for any reviewer.
• No branch protection on main, allowing accidental direct pushes to bypass review and automated checks entirely.

7.2.5Best Practices

• Keep pull requests small and focused on one logical change, making thorough review actually feasible.
• Enable branch protection requiring review approval and passing CI checks (7.5) before merge.
• Link every pull request to the issue or requirement it addresses for future traceability.