Lesson 03 · GitHub platform · projects

Projects

A project is a living view of your issues and PRs — a spreadsheet, a kanban board, and a roadmap, all reading from the same data. One project, many lenses.

You already know the units of work: issues describe what to do, PRs deliver the change, commits close them. A project is the organiser — it pulls those items together so you can see where everything stands, who's doing what, and what's blocked. It does not replace issues; it arranges them.

Where a project lives

Projects are not repo-scoped — this surprises most people. They live on your user profile or your organisation, and a single project can pull in issues and PRs from many repos. You find yours at github.com/users/YOUR-USERNAME/projects (or in the Projects tab on your profile page).

Why this matters Because a project isn't trapped inside one repo, it can track a goal that spans several repos — a website, an API, a docs repo — in one board. Knowing this early prevents the common mistake of creating one project per repo and then fighting to see the big picture.

Anatomy of a project

Items

The rows. An item is an issue, a pull request, or a draft issue (a quick note that hasn't become a real issue yet — no repo, no labels, just text). Draft issues are project-only until you convert them.

Fields

The columns. Every item carries built-in fields (title, assignees, labels, milestone, repository) and any custom fields you add — text, number, date, single-select, iteration. Custom field data lives on the project, not on the issue — this is a key difference from labels.

Views

Saved configurations — a particular layout + filter + sort + grouping. Like browser tabs: each is independent, looking at the same data differently.

Workflows

Built-in automations. Common ones: "when an issue is added → set Status to Todo", "when an item is closed → set Status to Done". Found in project Settings → Workflows.

Custom fields worth knowing

Type	What it is	Use case
`Single select`	Pick one option from a defined list	Status (Todo / In Progress / Done), Priority (High / Medium / Low)
`Text`	Free-form string	Notes, links, context
`Number`	Numeric value	Story points, estimates
`Date`	Calendar date	Due date, ship date (needed for Roadmap view)
`Iteration`	Repeating time blocks	Sprint planning — define two-week cycles, assign items to sprints

Field data lives on the project, not the issue If you add a "Priority" single-select to a project and mark an issue as "High", that priority value is only visible inside the project. On the issue page itself, there is no trace of it. Labels are the issue-side equivalent — visible everywhere. Keep this distinction in mind when choosing where to put metadata.

Three layouts, one dataset

Each view picks one of three layouts. You can have as many views as you want — a board for status tracking, a table for data entry, a roadmap for deadlines — all showing the same items.

Table

Spreadsheet grid. Items are rows, fields are columns. Sort, filter, group, bulk-edit — the densest view of your data.

Best for: seeing everything, editing in bulk

Board

Kanban columns. You pick which single-select field defines the columns (usually Status). Dragging a card between columns changes the field value — the board isn't just a display, it's an editor.

Best for: visualising workflow, daily standups

Roadmap

Timeline / Gantt chart. Requires a date or iteration field. Items are plotted against time — zoom from weeks to quarters.

Best for: deadlines, release planning

Adding items to a project

Multiple ways, all good:

Paste a URL — copy an issue or PR URL into the bottom row of a table view
Type # — triggers search across all repos you have access to; pick from results
Type plain text — creates a draft issue (project-only, no repo yet)
Bulk add — from an issue list: select issues, Add to project
gh CLI / API — scriptable for automation
Workflows — e.g. "auto-add every new issue in repo X"

Putting it together: the mental model

Think of it in layers:

Issues & PRs are the source of truth — they live in repos, carry labels and milestones, get closed by commits.
A project reads from those items and adds a planning layer on top — custom fields, views, automations — without changing the issues themselves.
Views are just saved filters on that planning layer. Change the view, not the data.

Your win — build a real project board

Go to this repo on GitHub → your profile → Projects tab → New project.
Pick "Board" template (or blank + switch to Board layout).
Add 2–3 existing issues from the learning repo (type # to search).
Add a custom single-select field called "Priority" with options: 🔥 High, Medium, Low.
Set a priority on each item.
Drag one item from "Todo" to "In Progress" — notice the Status field changes.
Create a second view as a Table — now you have two lenses on the same data.

That's a real, functioning project board. You can keep using it to track your learning.

Go deeper

Primary source — read this one: GitHub Docs — Quickstart for Projects. Walks through creating a project, adding items, custom fields, and views step by step.

Reference on layouts: GitHub Docs — Changing the layout of a view. Covers table, board, and roadmap configuration details.

Deeper on the data model: GitHub Docs — About Projects. The full feature overview.