Issues, Projects, Discussions

GitHub as a project management tool: tracking work, planning, discussing — beyond just code. FIND_VIDEO: search 'github issues projects discussions tutorial' — recommended channel: GitHub Training / Marc Pinet. Aim for 8 min or under.

8 minutesVideo LessonPDF notes

🎯 Free Guest Mode: You are learning for free. Sign in to save your completion progress and quiz answers.

Loading progress...

Key moments

Project Setup — The lesson begins by setting up a new GitHub Project board.
Select Automation Template — An automated Kanban template is selected to define initial workflow transitions.
Convert Task to Issue — A preliminary project task is converted into a full, traceable GitHub Issue.
Define Milestones — A new Milestone is created and the Issue is linked to it for scope management.
Milestone Automation Test — Closing the Milestone demonstrates how associated issues automatically transition to the 'Done' column.
Link Issue to PR — A new Pull Request is created and explicitly linked to the relevant project issues.
Verify Traceability — The bidirectional link between the Pull Request and the Issue is confirmed.
PR Merge Trigger — Merging the Pull Request automatically transitions all linked issues on the board to the 'Done' status.

PDF notes

Bottom line: You will learn to configure automated GitHub Project boards to manage development workflows seamlessly. By linking issues to milestones and pull requests, you ensure that task status updates automatically upon code completion, eliminating manual board maintenance. This mastery allows you to maintain perfect traceability between code changes and project status.

This lesson on Issues, Projects, Discussions is hands-on and example-driven. You will learn to configure automated GitHub Project boards to manage development workflows seamlessly. By linking issues to milestones and pull requests, you ensure that task status updates automatically upon code completion, eliminating manual board maintenance. This mastery allows you to maintain perfect traceability between code changes and project status.

What You'll Be Able To Do

Configure automated Kanban boards within GitHub Projects.
Convert project tasks into traceable GitHub Issues with metadata.
Group related issues under a common scope using Milestones.
Link development work (PRs) directly to project tracking issues.
Implement end-to-end workflow automation using PR merge triggers.
Verify bidirectional linking between PRs and Issues for full traceability.

Detailed Concept Walkthrough

1. End-to-End Workflow Automation

GitHub Projects automate task movement across the board by reacting to specific actions taken on linked artifacts like Issues and Pull Requests. This ensures the board reflects the true state of development without manual updates.

Mechanism: Automated Project templates (like Kanban with reviews) define state transitions (e.g., 'In Progress' -> 'Done') that are triggered by external events.
Execution Flow: When a linked PR is merged, the automation engine checks for associated Issues and automatically transitions them to the final column.
Best Practice: Always link Issues to the PR description using closing keywords (e.g., fixes #123) to ensure the board updates correctly upon merge.

git checkout -b feature/new-login
# ... code changes ...
git push origin feature/new-login

Key Takeaway: The Project board is a reactive visualization layer, not a manual data entry system.

2. Milestones for Scope Management

Milestones group related issues under a single deliverable or goal, acting as a container for a specific scope of work within a larger project. They help separate sprints or releases.

Mechanism: Issues are explicitly assigned to a Milestone during creation or editing, defining their contribution to that scope.
Under the Hood: Closing a Milestone triggers an optional automation that transitions all associated, incomplete Issues to the 'Done' column on the Project board.
Best Practice: Use Milestones to define time-boxed sprints or specific release versions, ensuring all linked issues contribute to that single goal.

Key Takeaway: Milestones define the scope boundary; closing them confirms the scope is complete.

3. The PR Completion Trigger

The final action of merging or closing a Pull Request is the explicit, non-reversible trigger that signals task completion and initiates automated board updates. Creating the PR only moves the task to 'In Review'.

Mechanism: The automation relies on the final state change of the PR (merged or closed) to determine if the linked Issue should be marked complete.
Under the Hood: Bidirectional linking ensures traceability; the PR history shows linked Issues, and the Issue history shows the resolving PR.
Best Practice: Differentiate between creating a PR (which moves the Issue to 'In Progress' or 'In Review') and merging it (which moves the Issue to 'Done').

git pull-request --base main --head feature/new-login

# PR Description MUST include:
# Resolves #42, fixes #43

Key Takeaway: Merging the PR is the final, definitive action that completes the linked Issue and updates the board.

Topics Covered in Issues, Projects, Discussions

Project Setup (00:19 - 00:59) — The lesson begins by setting up a new GitHub Project board.
Select Automation Template (00:59 - 01:13) — An automated Kanban template is selected to define initial workflow transitions.
Convert Task to Issue (01:21 - 02:24) — A preliminary project task is converted into a full, traceable GitHub Issue.
Define Milestones (02:32 - 04:41) — A new Milestone is created and the Issue is linked to it for scope management.
Milestone Automation Test (05:28 - 06:20) — Closing the Milestone demonstrates how associated issues automatically transition to the 'Done' column.
Link Issue to PR (06:29 - 08:33) — A new Pull Request is created and explicitly linked to the relevant project issues.
Verify Traceability (08:38 - 09:35) — The bidirectional link between the Pull Request and the Issue is confirmed.
PR Merge Trigger (09:37 - 12:20) — Merging the Pull Request automatically transitions all linked issues on the board to the 'Done' status.

Git Cheat Sheet

GitHub Projects — Visualizes workflow and automates status transitions
```
Projects > New Project > Automated Kanban
```
Convert to Issue — Turns a preliminary project task into a traceable artifact
```
Project Board Item > Convert to Issue
```
Milestone — Groups related issues under a common goal or deliverable
```
Issues > Milestones > New Milestone: 'V1.0 Release'
```
Link Issue to PR — Connects code changes to the project tracking system
```
PR Description: fixes #101
```
PR Merge Action — Final trigger for automated board transition to 'Done'
```
Merge Pull Request button
```

Comparison Table

Artifact	Primary Function	Scope
Issue	Single, actionable task	Smallest unit of work
Milestone	Group related issues	Time-boxed goal or release
Project	Workflow management	Large, ongoing initiative

Common Pitfalls

Mistake: Forgetting to link the Issue in the PR description. Avoid: Always use fixes #N or resolves #N in the PR body.
Mistake: Assuming creating a PR completes the Issue. Avoid: Only the final merge/close action triggers the 'Done' transition.
Mistake: Using Milestones for general categorization instead of scope. Avoid: Reserve Milestones strictly for specific deliverables or sprints.
Mistake: Manually moving linked issues to 'Done'. Avoid: Rely on the PR merge automation to handle the transition.

FAQs

What is the difference between a Project Item and an Issue? A Project Item is a preliminary task on the board; an Issue is a fully traceable artifact with metadata, labels, and assignments.
Does closing a Milestone always move issues to 'Done'? Yes, if the automation is configured, closing the Milestone forces all associated issues to transition to the final column, regardless of their current status.
How do I ensure bidirectional linking between a PR and an Issue? Linking the Issue in the PR description automatically creates the link; GitHub handles the reverse link for traceability in the Issue history.
Can I use a Project board without automation? Yes, but you lose the efficiency benefit; you would have to manually update the status of issues as development progresses.

Common pitfalls

Mistake: Forgetting to link the Issue in the PR description. Avoid: Always use `fixes #N` or `resolves #N` in the PR body.
Mistake: Assuming creating a PR completes the Issue. Avoid: Only the final merge/close action triggers the 'Done' transition.
Mistake: Using Milestones for general categorization instead of scope. Avoid: Reserve Milestones strictly for specific deliverables or sprints.
Mistake: Manually moving linked issues to 'Done'. Avoid: Rely on the PR merge automation to handle the transition.

This tutorial provides a practical, step-by-step guide to using **GitHub Projects Automation** within *GitHub*. After watching, a learner will be able to effectively manage project workflows using GitHub Projects automation features linked to issues and pull requests. ### **Curriculum Alignment: Topics Covered** 1. **Project Setup and Context (00:19 - 00:59)** * **Concept:** Structuring large projects using the GitHub Project board, often analogous to "Epics" in Scrum. * **Action:** Navigating to the Projects tab, creating a new project, naming it, and providing a description. 2. **Selecting an Automated Project Template (00:59 - 01:13)** * **Concept:** Choosing a project board structure that supports predefined workflow transitions (e.g., reviews, in progress). * **Action:** Selecting and applying the "automated Kanban with reviews" template. 3. **Creating and Converting Project Items to Issues (01:21 - 02:24)** * **Concept:** Turning preliminary project tasks into actionable, traceable GitHub issues complete with metadata. * **Action:** Adding tasks directly to the board, converting them to full GitHub Issues, assigning users, and applying labels (e.g., enhancement). 4. **Utilizing Milestones for Scope Management (02:32 - 04:41)** * **Concept:** Using Milestones to group related issues under a common goal or deliverable, separating scope within a larger project. * **Action:** Creating a new Milestone and linking a newly created issue to it. 5. **Milestone-Based Workflow Automation (05:28 - 06:20)** * **Concept:** Automating task completion status by linking completion actions (closing a milestone) to issue movement on the board. * **Action:** Closing a Milestone and verifying that all associated issues automatically transition to the 'Done' column. 6. **Linking Issues to a New Pull Request (06:29 - 08:33)** * **Concept:** Connecting development work (in a branch) to the project tracking system via a Pull Request (PR). * **Action:** Creating a new Pull Request (comparing branches) and explicitly linking it to specific project issues. 7. **Cross-Linking Issues and Pull Requests (08:38 - 09:35)** * **Concept:** Verifying bidirectional linking between project artifacts to ensure traceability. * **Action:** Confirming that the PR history reflects linked issues and linking the new PR back to the project board. 8. **PR Merge Automation and Board Efficiency (09:37 - 12:20)** * **Concept:** Using the PR merge action as the final trigger for automated project workflow completion. * **Action:** Merging the Pull Request and observing the automatic transition of all linked issues on the board to the 'Done' column, bypassing manual updates. ### **Learning Outcomes** * **Proficiency:** Configure and manage automated GitHub Project boards, create issues, and apply labeling and assignment strategies. * **Workflow Management:** Successfully implement end-to-end automation by linking issues to Milestones and Pull Requests, ensuring the board updates without manual intervention upon completion actions. * **Tooling:** Comfortably navigate and utilize the core interfaces of GitHub Issues, Pull Requests, and Projects. ### **Advanced/Tricky Concepts** * **The PR Completion Trigger:** The difference between creating a Pull Request (a pre-requisite step to merging) and the act of merging/closing the PR. It is the final merge/close action that serves as the explicit trigger for automatically updating the linked issues on the Project board.

Frequently asked questions

What is the difference between a Project Item and an Issue?

A Project Item is a preliminary task on the board; an Issue is a fully traceable artifact with metadata, labels, and assignments.

Does closing a Milestone always move issues to 'Done'?

Yes, if the automation is configured, closing the Milestone forces all associated issues to transition to the final column, regardless of their current status.

How do I ensure bidirectional linking between a PR and an Issue?

Linking the Issue in the PR description automatically creates the link; GitHub handles the reverse link for traceability in the Issue history.

Can I use a Project board without automation?

Yes, but you lose the efficiency benefit; you would have to manually update the status of issues as development progresses.

How was this lesson?

Your feedback helps us refine explanations and catch bugs.