Notes on the use and management of GitHub projects

Learning how to take project management to the next level

I recently spent some time focusing on my approach to project management, in hopes of developing skills to be a better team lead. One way I try to manage work is using GitHub Projects.

Below are some links and notes about what I’ve recently learned about GitHub projects.

In the spirit of attempting to do more link- and micro-blogging, some of these notes may seem disjointed, incomplete, or incohorent. However, it’s what I’ve learned thus far about managing projects in GitHub.

What are GitHub projects?

A project is an adaptable spreadsheet, task-board, and road map that integrates with your issues and pull requests on GitHub to help you plan and track your work effectively.

More about projects can be found here. Instructions on how to create a GitHub project can be found here.

Either an organization project or user project can be created.

Projects are useful for organizing issues from other repos. Check out the docs to learn more about how to create issues.

A project can have a description and associated README. Here’s some links to resources on how to write a useful README:

• How to Write a Good README File for Your GitHub Project (freeCodeCamp)
• How To Write a USEFUL README On Github
• README template I use for most of my projects.

Most of the above are repo focused, so it might be good to create a template specific for a project.

Adding issues to a project

Use the ‘+ Add item’ to add issues or pull requests to a project. You can then locate the issue via the UI prompts, or you can paste the issue or pull request URL (very helpful). The bulk add issues and pull requests and Adding multiple issues or pull requests from a repository features seem really useful.

Adding fields to help manage projects

An iteration field seems useful for managing sprint intervals. More about how to setup an iteration field can be found here.

Useful features to explore further

• Custom fields to add metadata for richer views of item attributes.
• Project automation (built-in automations, using Actions to automate projects)

GitHub Command Line Interface (CLI) tool

Tip: get the gh command-line tool. More about how to get started can be found here.

Useful commands for managing issues and projects

Create an issue with an interactive prompt.

gh issue create

Sometimes you fall into common patterns when creating issues, so command flags are often helpful.

gh issue create
gh issue create -a "@me" -t "New project to work on" -l "project"
gh issue create -a "@coworker" -t "Fix this" -l "bug"

More about how to manage issues in a repo via the command line can be found here.

You can list all your projects using the following commands:

# Your projects
gh project list

# Organizational owned projects
gh project list --owner owner_of_project

View the project either in the command line or open it in a web browser.

# From command-line
gh project view 5

# Open in web browser
gh project view 5 --web

You can edit the project README by running the following:

gh project edit 5 --readme "Here be some info about the project"

However, this command seems to only allow you to add a new README and not edit it.