How to Use GitHub Projects Effectively

Most engineering teams still plan work in one tool and ship it in another. Issues live in Jira or Trello, pull requests live in GitHub, and every status change requires a human to copy context across tabs. GitHub Projects removes much of that friction by keeping planning, issue tracking, and delivery close to the code.

Current GitHub Projects is the planning layer on top of issues and pull requests: custom fields, saved views, built-in automations, roadmaps, charts, and API access. It replaces Projects (classic), not the same product with a new coat of paint.

For teams that already live in GitHub, the value is straightforward:

• Less context switching between a tracker and the code host
• Fewer stale status updates because issue and pull request state can drive project state
• One place to plan cross-repository work without losing repository-level detail
• A workflow that works for a two-person open source project, an inner source program, or a larger engineering org

Getting Started¶

Create the Project¶

The first decision is scope: create the project under your own account or under an organization.

A practical rule:

• If the project is for you, create it at the user level.
• If the project is for a team, create it at the organization level.

To create one in the GitHub UI:

1. Go to your profile or organization.
2. Open Projects.
3. Click New project.
4. Start from a blank project unless you already have a template you trust.
5. Name it after the workflow, not just the team.

Good names:

• Infrastructure Automation Maintenance
• Multi-Repo Sprint Board
• Shared Maintainer Workflow
• Open Source Release Coordination

Weak names:

• Project 1
• Team Board
• Stuff

Link Repositories¶

Projects become more useful the moment they are linked to the repositories that generate the work. Linking repositories makes it easier to add issues and pull requests, power automations, and keep the project close to the code.

In the UI:

1. Open the project.
2. Open the project menu.
3. Go to the project settings.
4. Link the repositories that should feed this project.

For an engineering team, link every repository that regularly contributes work to the same delivery stream. For open source or inner source maintainers, this often means linking the primary repository, supporting libraries or SDKs, documentation, examples, and release tooling that move together.

Assign Access by Team¶

If you're using an organization project, don't stop at creating the project. Set up access so the right teams can actually manage it.

In the UI:

1. Open the project.
2. Go to Settings.
3. Open Manage access.
4. Add the relevant GitHub teams.
5. Assign the role each team should have.

For a maintainer-heavy organization, team-based access is usually cleaner than assigning people one by one. It scales better, it survives personnel changes, and it matches the way repository ownership often already works.

A practical pattern is to grant project access to repository-aligned maintainer teams such as:

• org/blue-maintainers
• org/green-maintainers
• org/orange-maintainers
• org/purple-maintainers

If those teams are responsible for triage, planning, and workflow maintenance, giving them project admin access can make sense. If they only need to update and view items, use a less privileged role that matches how you want the project governed.

Add Items the Right Way¶

Modern Projects supports two useful item types from day one:

• Draft issues: lightweight planning items that live only in the project
• Issues and pull requests: real repository-backed work items

Use draft issues when:

• you're brainstorming backlog items
• the work isn't ready for a repository yet
• you're doing sprint planning and want to capture loose tasks quickly

Use real issues when:

• the work should have repository history
• you want assignees, labels, milestones, or notifications
• the item is ready for execution

Structured issue forms make repository-backed items easier to triage. See How to Write Effective GitHub Issue Templates.

A healthy pattern looks like this:

1. Capture early ideas as draft issues during planning.
2. Refine them until they are actionable.
3. Convert the ones that matter into real issues in the appropriate repository.

That distinction matters. A project full of real issues too early creates noise. A project full of draft issues forever creates shadow work. Start light, then promote work into the repository when it's ready.

Master Custom Fields¶

GitHub Projects gets powerful when you stop treating it like a simple board and start treating it like a data model. Your custom fields are the schema that your views and automation depend on.

For most teams, the minimum useful schema looks like this:

Status¶

This is the field most teams get wrong first. They add too many states and recreate a workflow engine inside a project.

Start with four values:

That's enough for most software teams.

If your team really needs it, add Blocked later. Don't start with ten status values just because another tool had them.

For maintainers working across repositories with an active pull request review cycle, a richer status model can be worth it. A practical example looks like this:

This kind of status field fits multi-repository maintenance especially well. It helps you separate "code exists", "review is happening", "the PR merged", and "the overall work is truly done". Those states are often not the same when you are coordinating release notes, docs, compatibility updates, or follow-on cleanup.

Priority¶

Priority is not the same thing as status. A P0 item can still be Backlog.

Use a simple scale:

If you add P3, teams often stop treating priority as a real decision. Keep the scale small.

If numeric-style priority labels feel too formal or too product-management-heavy, a plain-language scale can work better:

This model is especially effective for teams balancing work across several repositories because it reads naturally at a glance. When you are juggling a bug, a release task, a documentation fix, and an enhancement request across multiple repositories, Urgent / High / Medium / Low is often easier to scan and easier to explain to contributors than P0 / P1 / P2.

The label style matters less than the shared definition behind it. The field is only useful if it helps the team decide what gets worked next.

Size or Estimate¶

Pick one estimating model and stick to it.

For teams that want quick planning:

For teams already using agile estimation, use a number field or a single-select field with story points such as 1, 2, 3, 5, and 8.

For maintainer teams and internal platform groups, this X-Small through X-Large model is often more useful than story points. It is fast to apply, easy for occasional contributors to understand, and good enough for planning a mix of bug fixes, release tasks, documentation updates, and cross-repository changes.

The main rule is consistency. A field no one trusts becomes a decorative column.

Iteration¶

The iteration field is where GitHub Projects starts to feel like a real sprint workspace instead of a generic kanban tool.

A good setup:

1. Create an Iteration field.
2. Choose your sprint cadence, usually one or two weeks.
3. Add scheduled breaks for holidays or company shutdowns if your team needs them.
4. Use iteration as the default planning bucket, not milestone labels. For release-scoped grouping in a single repository, GitHub Milestones as Release Payloads is often the better fit.

Iterations work especially well because GitHub Projects can use them in table, board, and roadmap views. That makes one field do work across planning, standups, and reporting.

External Tracking IDs¶

Sometimes GitHub Projects is the operational hub, but not the only system that matters. You may still need to reference a Jira issue, a support case, an internal engineering tracker, or another enterprise record.

A simple text field handles this well.

Examples:

This is one of those fields that looks minor but becomes very useful during release prep, escalations, and status reporting. It gives maintainers a lightweight way to preserve traceability without forcing the GitHub issue title or body to carry every external identifier.

Design the Views That Matter¶

A good project has more than one view. Different conversations need different slices of the same data. In practice, that usually means a mix of:

• Shared team views for backlog grooming, planning, and review
• Personal working views for "what do I need to move today?"
• Repository- or area-specific views when one project spans many related codebases

Planning View¶

The planning view should feel like a backlog spreadsheet, not a kanban lane view.

Set it up like this:

1. Create a new view named Planning.
2. Set the layout to Table.
3. Show these columns: Title, Repository, Status, Priority, Size, Iteration, Assignees
4. Group by Iteration.
5. Sort by Priority, then by Size.
6. Filter out completed work if you want a cleaner backlog.

This view is where sprint planning, backlog grooming, and cross-repository prioritization should happen. For maintainers coordinating several repositories, it's often the best place to line up bug fixes, release prep, documentation updates, and compatibility work in one place.

If you use numeric estimates, turn on Field sum for the estimate column. Seeing the point total per iteration is one of the easiest ways to avoid overcommitting the sprint.

Maintainer View¶

One of the most useful views in a multi-repository project is a personal working view, usually something like My items.

Set it up like this:

1. Create a new view named My items.
2. Set the layout to Table.
3. Filter to: assignee:@me
4. Show columns that help you act quickly, such as: Title, Status, Linked pull requests, Repository, Sub-issues, Priority
5. Group by Status.
6. Hide empty groups if you want a tighter operational view.

This kind of view is excellent for maintainers because it answers a different question than the planning board. It isn't "what is the whole project doing?" It's "what is on me right now?"

In a view like this, the status groups are doing real work. You can scan:

• what is still in Backlog
• what is actively In Progress
• what is Ready for Review
• what is already In Review
• what has already been Completed
• which items already have linked pull requests

That last point matters more than it sounds. Seeing the Linked pull requests column beside the item title makes it much easier to connect planning state to actual code movement. At a glance, you can tell which assigned items already have active PRs tied to them.

Daily Standup View¶

The daily standup view should answer one question quickly: what is moving right now?

Set it up like this:

1. Create a new view named Daily Standup.
2. Set the layout to Board.
3. Group by Status.
4. Filter to the current iteration.
5. Optionally hide Completed if you want a tighter daily focus.
6. Keep cards lightweight: title, assignee, repository, and priority are usually enough.

With a richer maintainer workflow, this usually means columns like:

• Backlog
• In Progress
• Ready for Review
• In Review
• Completed

If your team wants standups to stay short, don't use this view to debate priority or redesign the sprint. That belongs in the planning view.

If you're a solo maintainer, this still works. The view becomes a quick operational snapshot of what is actively being coded, what is waiting for review, and what can ship next.

Repository or Area Views¶

When one project covers many repositories, it's often worth creating focused views for a product area or repository family.

Examples:

• Platform APIs
• Shared Tooling
• Developer Docs
• Release Engineering

Set these up with repository filters, then choose the layout that matches the work. A table view is great for triage and dependency tracking. A board view is better when you want to focus on status movement within one area.

A repository-scoped view can look like this:

1. Create a view named Platform APIs.
2. Filter it to the repositories that belong in that slice of work.
3. Group by Status.
4. Keep the active statuses visible: Backlog, In Progress, Ready for Review, In Review, Completed
5. Include columns like Linked pull requests and Sub-issues if those relationships matter for that area.

This kind of view is especially useful when one initiative spans several related repositories. It lets you focus on one ecosystem at a time without losing the benefits of having everything in one project.

That repository-scoped view keeps the project from feeling overwhelming. Instead of one giant backlog for everything, you can jump into the slice that matches the work you're handling at that moment.

Executive View¶

Executives and project leads usually don't want a kanban board. They want a time-based view of major initiatives. In open source and inner source, this is often closer to a portfolio roadmap: upcoming releases, milestone work, deprecations, or cross-repository compatibility efforts.

Set it up like this:

1. Create Start date and Target date fields if you haven't already.
2. Create a new view named Executive.
3. Set the layout to Roadmap.
4. Configure the roadmap to use Start date and Target date.
5. Filter the view to only high-level work, such as: label:epic or a custom field like Track = Initiative
6. Zoom out to Quarter or Year.
7. Slice by repository, team, or priority if that helps leadership discussions.

Roadmap views in GitHub Projects can use date fields or iteration fields to position work on the timeline. For cross-repository initiatives, date fields are usually clearer because they allow longer-running items that don't fit neatly inside one sprint.

A useful practice here is to track epics as real issues in a planning or meta repository, then link the implementation issues from the working repositories underneath them through normal issue references and project filters. For example, one roadmap item might represent a coordinated release across an application repository, its supporting library, and the related documentation.

Automation¶

GitHub Projects includes built-in workflows that can update item status, auto-add items from repositories, and archive completed work. This is where Projects becomes especially useful for multi-repository maintenance, because repository events can drive project state instead of relying on maintainers to update cards by hand.

You can manage these workflows from the project menu under Workflows.

Auto-Add New Issues from Specific Repositories¶

This is the first automation most teams should enable.

Setup:

1. Open your project.
2. Open the project menu.
3. Click Workflows.
4. Create a workflow to auto-add items.
5. Select the repository that should feed this workflow.
6. Add a filter so you don't pull in everything blindly.

If your project spans many repositories, it's often cleaner to create one add-to-project workflow per repository instead of one giant catch-all rule. That gives you a durable pattern like this:

• Add to Project: Blue
• Add to Project: Green
• Add to Project: Orange
• Add to Project: Purple
• Add to Project: Yellow

That approach works well for maintainers because each repository can have slightly different intake rules without turning the project into a giant filter puzzle.

Good starter filters:

is:issue is:open

is:issue is:open label:bug

is:issue is:open -label:epic

is:issue is:open label:release

If you want both issues and pull requests to enter the project automatically, a filter like this is practical:

is:open

Then scope the workflow to the selected repository and item types you actually want to track.

For many maintainer-led workflows, a filter like is:issue is:open is often enough. For product teams, be more selective so the project doesn't become a mirror of every repository issue list.

Automate Status Changes¶

This is where a richer maintainer workflow really pays off. Instead of stopping at a simple start-and-finish model, you can let pull request review activity and item lifecycle events update statuses automatically.

A strong baseline looks like this:

This gives you a project that stays aligned with what is actually happening in GitHub.

Set Backlog When an Item Is Added¶

This is a great default for a cross-repository project.

Setup:

1. Open Workflows.
2. Select Item Added to Project.
3. Configure it for the item types you care about, usually issues and pull requests.
4. Set Status = Backlog.

This works especially well when you have many repository-specific add-to-project workflows, because new work lands in one predictable state before you triage it.

Move Status on Review Activity¶

If your project tracks pull requests directly, built-in review workflows are surprisingly useful.

Setup:

1. Open Workflows.
2. Enable Code Changes Requested and set Status = Changes Requested.
3. Enable Code Review Approved and set Status = Changes Approved.
4. Optionally enable Pull Request Merged and set Status = Changes Merged or Completed.

For teams using review-driven workflows, this is one of the highest-value automations in Projects. It keeps the project synced to review reality instead of leaving maintainers to remember whether a PR is waiting on feedback, waiting on merge, or truly done. Pair it with a solid pull request template so review context stays consistent.

Move Work to a Terminal State When an Issue Closes or a Pull Request Merges¶

This part is easier. GitHub Projects ships with default workflows for it.

Setup:

1. Open the project.
2. Open Workflows.
3. Review the default workflow for item closed and ensure it sets Status = Completed or your equivalent terminal state.
4. Review the default workflow for pull request merged and ensure it also sets Status = Changes Merged, Completed, or the terminal state that best matches your workflow.
5. Save and enable both workflows if they aren't already on.

For most teams, these should stay enabled. They are the easiest way to keep the project honest without asking engineers to drag cards manually after every merge.

Reopened Means Backlog Again¶

Reopened work is one of the easiest things to miss if you don't automate it.

Setup:

1. Open Workflows.
2. Enable Item Reopened.
3. Set Status = Backlog or Planned, depending on how your team re-triages reopened work.

This helps because a reopened bug or pull request should usually re-enter the project as active triage, not stay stranded in a completed state.

Auto-Archive Closed Work¶

Once the project has accurate terminal states, auto-archive keeps old work from piling up forever.

Setup:

1. Open Workflows.
2. Select Auto-archive Items.
3. Add a filter for the completed items you want to archive on a schedule.

A practical example looks like this:

is:issue is:closed updated:<@today-1m

Using updated: is helpful because it lets GitHub re-run the workflow on a schedule and archive items after they have stayed closed for a while, instead of immediately disappearing from the project.

Tips for Power Users¶

Use GitHub Actions and GraphQL When Built-In Automation Stops Short¶

Built-in workflows are great until you need to update one project item based on an event that happens on another item. A common example is moving an issue to In Progress when a pull request linked to that issue is opened.

That's a good use case for GitHub Actions plus the GraphQL API.

name: project-status-sync

on:
  pull_request:
    types: [opened, reopened]

jobs:
  update-project:
    runs-on: ubuntu-latest
    steps:
      - name: Move project item to In Progress
        env:
          GH_TOKEN: ${{ secrets.PROJECT_TOKEN }}
          PROJECT_ID: ${{ secrets.PROJECT_ID }}
          ITEM_ID: ${{ secrets.PROJECT_ITEM_ID }}
          STATUS_FIELD_ID: ${{ secrets.STATUS_FIELD_ID }}
          IN_PROGRESS_OPTION_ID: ${{ secrets.IN_PROGRESS_OPTION_ID }}
        run: |
          gh api graphql -f query='
            mutation($project:ID!, $item:ID!, $field:ID!, $option:String!) {
              updateProjectV2ItemFieldValue(input: {
                projectId: $project
                itemId: $item
                fieldId: $field
                value: { singleSelectOptionId: $option }
              }) {
                projectV2Item {
                  id
                }
              }
            }' \
            -F project="$PROJECT_ID" \
            -F item="$ITEM_ID" \
            -F field="$STATUS_FIELD_ID" \
            -F option="$IN_PROGRESS_OPTION_ID"

In a real workflow, you would usually look up ITEM_ID dynamically from the linked issue or pull request rather than storing it as a fixed secret. The bigger point is that GitHub Projects has a real API surface, so you're not boxed into the built-in workflow menu.

Learn the Keyboard and Bulk-Edit Habits¶

You don't need a long list of shortcuts to get faster. You need a few habits:

• Press ? anywhere on GitHub to open the keyboard shortcut reference.
• Treat the table view like a spreadsheet: edit fields inline instead of opening every item.
• Use multi-select and bulk-edit for iteration changes, priority changes, and cleanup at the start or end of a sprint.

Teams that do this consistently spend much less time "maintaining the project" and more time using it to make decisions.

GitHub CLI Reference¶

The GitHub UI should be the default path for most teams getting started. The gh CLI becomes more useful later, when you want to script setup, inspect field IDs, or seed items quickly from the terminal.

The minimum token scope is project.

gh auth refresh -s project

Use these commands as a reference:

This is especially useful when you need to confirm the exact project schema before writing automation against it.

GitHub Projects works best when it is treated as a planning layer for the work already happening in GitHub, not as a separate bureaucracy. A small set of fields, a few purpose-built views, and a handful of automations is usually enough to replace a lot of external tooling.

If your team already lives in GitHub, build one project this week: define Status, Priority, Size, and Iteration, create the planning and standup views, and turn on the default automations. Start by linking the repositories that actually ship together and let the project become the shared operational layer above them. Once that foundation is working, add the roadmap and the advanced automation only where they solve a real problem.

References¶

• How to Write Effective GitHub Issue Templates
• GitHub Milestones as Release Payloads
• How to Write an Effective GitHub Pull Request Template