Projects and Wikis

Plan work on a Projects board and document your repo with a Wiki.

GitHub bundles planning and documentation tools alongside your code.

Projects

Projects are flexible boards and tables that track issues and PRs. Drag cards across columns like To do, In progress, and Done, or switch to a table or roadmap view. Fields, filters, and automation help you manage larger efforts.

Wikis

Each repo can have a Wiki — a collection of Markdown pages for longer documentation, guides, and design notes that would clutter the README.

Example

# A repo's wiki is itself a Git repo you can clone
git clone https://github.com/you/my-project.wiki.git

# Add and push pages like any repo
cd my-project.wiki
git add Home.md
git commit -m "Add wiki home page"
git push

When to use it

A product team uses a GitHub Project board with swimlane columns (Backlog, In Progress, In Review, Done) to manage a two-week sprint.
An open-source project uses the Wiki to document the contributor guide, keeping it editable by community members without touching the source tree.
A team links issues and pull requests to a Project so progress toward a milestone is automatically reflected on the board.

More examples

Create a Project board via CLI

Creates a new GitHub Project and confirms it appears in the list; items and columns can then be added in the browser or via API.

gh project create \
  --owner @me \
  --title "Q3 Sprint Board"

gh project list --owner @me
# NUMBER  TITLE           STATE
# 1       Q3 Sprint Board OPEN

Add an issue to a Project

Links an existing issue to the project board so it appears as a card that can be moved through workflow columns.

# Get the project ID first
gh project list --owner @me --format json | jq '.[0].id'

# Add issue #42 to the project
gh project item-add 1 --owner @me --url https://github.com/owner/repo/issues/42

Edit a wiki page via the API

The wiki is a separate git repo at repo.wiki.git; you clone, edit, and push it like any other repository.

# List wiki pages with GitHub CLI
gh api repos/{owner}/{repo}/git/trees/HEAD \
  --jq '.tree[] | select(.path | endswith(".md")) | .path'

# Push wiki content
git clone https://github.com/owner/repo.wiki.git
cd repo.wiki
echo '# Contributing\nFork, branch, PR.' > Contributing.md
git add . && git commit -m "docs: add contributing guide"
git push

Discussion

Be the first to comment on this lesson.