GitHub Projects, Planning, And Delivery Flow

GitHub Projects is a planning layer on top of issues, pull requests, and repository work. It can show a team what is planned, what is blocked, what is in progress, what is ready for review, and what has shipped. It can also become a second system where people move cards around instead of making progress. The difference is whether the project board reflects real delivery decisions or merely decorates work that is already tracked somewhere else.

Use GitHub's official documentation for current product behavior. GitHub documents Projects in pages such as About Projects, Understanding fields, Changing the layout of a view, and Automating Projects. Exact features, field types, and automation options change over time, so teach the model first: a project should make decisions visible, connect planning to real issues and pull requests, and reduce coordination cost.

Projects Are Not A Substitute For Good Issues

A project board filled with vague issues is still vague. Projects can group work, add fields, show views, and automate status changes, but they cannot create missing reproduction steps, unclear ownership, or absent acceptance criteria. If an issue title says Fix auth, adding it to a project does not tell a developer which login flow is broken, what the expected behavior is, or how to verify the fix.

Start with issue quality. Each item should state the work, context, owner or next action, and evidence needed for completion. Then use Projects to answer questions the issue list alone does not answer: what is planned for this iteration, what is blocked, which pull requests are waiting on review, which work belongs to a release, which area is overloaded, and what is ready for a new contributor.

For a PHP application team, a project might track a checkout reliability push. Issues cover coupon validation, payment retry behavior, database migration, API error shape, worker idempotency, documentation, and deployment checks. Pull requests link to those issues. The project view then shows whether the release is still blocked by the migration, whether the API work is under review, and whether the documentation was forgotten.

Fields Give Work A Shared Vocabulary

Fields are useful when they encode decisions the team actually uses. Common fields include status, priority, size, milestone, iteration, area, target environment, risk, owner, or planned release. A field should have a clear meaning. If Priority: High only means that someone was excited when creating the issue, the field is noise. If Priority: High means release-blocking or customer-impacting under a written policy, it helps decision-making.

Status fields deserve special care. Todo, In progress, and Done are often not enough for software work. A more useful flow might include Needs triage, Ready, In progress, In review, Blocked, Ready to deploy, and Done. The right states depend on the team. Too many states create process overhead; too few states hide important waits.

Avoid fields that duplicate data already visible elsewhere unless the duplicate serves a purpose. A project does not need a manual PR open checkbox if linked pull requests already make that visible. It may need a Release risk field because GitHub cannot infer whether a small PHP config change is riskier than a large documentation edit. Manual fields should be worth the human attention they require.

Views Serve Different Audiences

A view is a way to look at the same underlying items. A table view may help maintainers sort by priority and owner. A board view may help a team see flow from ready work to review. A roadmap view may help stakeholders understand timing. A filtered view may show only the current release, only authentication work, or only pull requests waiting for review.

Do not design one view to satisfy every audience. Developers need actionable next steps. Maintainers need backlog health and blocked work. Stakeholders need status without implementation noise. A board that tries to serve all three often becomes crowded and ambiguous.

Good views answer named questions. Current iteration answers what the team is doing now. Needs review answers what reviewers should inspect next. Blocked answers where intervention is needed. Release readiness answers what must happen before launch. If nobody can name the question a view answers, delete or redesign the view.

Automation Should Remove Clerical Work

Project automation can add items, move status values, or respond to issue and pull request changes. Automation is useful when it removes clerical work without hiding judgment. Moving an item to In review when a linked pull request opens may be helpful. Automatically marking an item Done when any pull request merges may be wrong if the issue needs documentation, deployment, or follow-up verification.

Automation should match the team's definition of done. For a PHP deployment task, merged code may not be done until the release is deployed, smoke checks pass, and monitoring stays healthy. For documentation, merge may be enough. For a security fix, done may require advisory publication, package release, and communication to users. Projects should reflect those differences instead of pretending every merge means the same outcome.

Review automation rules like code. Ask what event triggers the rule, what item changes, who can cause the event, and whether the new status can mislead people. Automation that silently moves work to done is especially risky because it can hide unfinished operational tasks.

Projects And Pull Requests

Projects are most useful when they connect planning to pull requests. An issue can describe the work, the pull request can implement it, and the project can show where it sits in the delivery flow. This avoids the common failure where a project board says In progress but nobody knows whether a branch exists, whether review is blocked, or whether CI failed.

A practical workflow is to require each meaningful pull request to link to an issue or project item unless the change is truly trivial. The project item should make the acceptance criteria visible. The pull request should provide implementation and test evidence. The project view should show review and release status. Each layer has a job; none should replace the others.

For large work, split the project item. Rewrite billing is not useful as one card. Better items might cover schema preparation, read-model compatibility, API changes, admin UI, migration backfill, monitoring, rollout, and cleanup. The project can then show partial progress without pretending the whole rewrite is almost done because one branch merged.

WIP Limits And Flow

A project board can reveal too much work in progress. If every column is full and nothing moves to done, the team may be starting more than it finishes. WIP limits do not need to be formal to be useful. The team can agree that only a few items should be In progress per developer or that review should be cleared before new work starts.

Blocked work should be visible and specific. A Blocked field without a reason is only a label. A good blocked item links to the dependency: waiting on product decision, missing test environment, upstream provider issue, unavailable reviewer, migration conflict, or security review. If blocked work sits for weeks, the project should force a decision: unblock, rescope, defer, or close.

Projects also help prevent review starvation. A Needs review view can show old pull requests, owners, and risk. If review is always the bottleneck, the solution may be smaller pull requests, clearer ownership, more reviewer time, or better automated checks. Moving cards around is not the fix; the board simply exposes the constraint.

When Projects Become Overhead

Projects become overhead when they duplicate another tracker, require manual updates nobody trusts, hide work behind private fields, or serve reporting more than delivery. If the source of truth is Jira, Linear, or another planning tool, GitHub Projects may still help for open-source or repository-local views, but the team must define which tool owns status. Two authoritative trackers create drift.

A project also fails when it is too detailed for the team's scale. A solo maintainer may need a simple triage view and release checklist, not a complex multi-view program board. A larger team may need structured fields and automation. Process should scale with coordination cost.

Use Projects when they reduce questions: What should I work on next? What is blocked? What needs review? What is in this release? What shipped? What is abandoned? If the project creates more questions than it answers, simplify it.

Review Checklist

Review a GitHub Project by asking whether every view has an audience and question, whether fields have clear meanings, whether issue quality is strong enough to support planning, whether automation matches the team's definition of done, whether blocked work has reasons, whether review bottlenecks are visible, and whether the project is the source of truth or only a repository-local view.

The learner should be able to decide when GitHub Projects are useful, design fields and views around real decisions, connect issues and pull requests to delivery flow, use automation cautiously, identify WIP and blocked-work problems, and remove project overhead that does not help the team ship better software.