Github Projects is a planning and tracking tool when on working on Github Repo.
A project has an adaptable view that can be changed at anytime between:
- Spreadsheet (Table)
- Taskboard (Board)
- Roadmap (Roadmap)
Projects directly integrates with Issues and Pull Requests.
Project have build-in workflows to automate common actions.
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.
You can create and customize multiple views by filtering, sorting, grouping your issues and pull requests, visualize work with configurable charts, and add custom fields to track metadata specific to your team.
Your projects are built from the issues and pull requests you add, creating direct references between your project and your work.
Warning
Must remember:
- Information is synced automatically to your project as you make changes, updating your views and charts.
- This integration works both ways, so that when you change information about a pull request or issue in your project, the pull request or issue reflects that information.
You can use custom fields to add metadata to your issues, pull requests, and draft issues and build a richer view of item attributes.
You’re not limited to the built-in metadata (assignee, milestone, labels, etc.) that currently exists for issues and pull requests.
For example, you can add the following metadata as custom fields:
- A date field to track target ship dates.
- A number field to track the complexity of a task.
- A single select field to track whether a task is Low, Medium, or High priority.
- A text field to add a quick note.
- An iteration field to plan work week-by-week, including support for breaks.
A project is componsed of multiple views, you can add more views to your project.
Each view's layout can be changed at anytime to accommodate the project use-case
- Table: This layout is great for your traditional ticket tracker and large amount of task
- Board: This layout is great for your agile tasks and understand clearly the state of issues
- Roadmap: This layout is great for planning based on a timeline
For your layout you can configure your data based on multiple options
- Fields: Add custom data fields to each project item (eg: status, assignees)
- Column by: Organize board columns based on specific fields (eg: status)
- Group by: Group by items into rows based on a chosen field (eg: assignee, label)
- Sort by: Define the order of items within columns or groups (eg: by priority)
- Fields sum: Show a summary or total of a particular field for all items in a column/group
- Slice by: Filter visible items on the board by specific field (eg: milestone, label)
- Zoom level: (Roadmap only) Adjust the view of the roadmap timeline (daily, monthly, quarterly)
- Dates: (Roadmap only) Set and view start and end date for each time on the roadmap
Remeber about items that:
- Your Github Project Items have custom fields
- You can create new fields
- Provide options to easily fill in the fields
Github Projects offers more advance and flexible project management tools compared to Github Classic Projects, which is simpler and more straightforward.
| Feature | Github Projects | Github Classic Projects |
|---|---|---|
| Interface | New more dynamic interface with tables, board and views | Traditional board view similar to Trello |
| Flexibility | Highly customizable with different view and fiels | Limited customization options |
| Automation | Supports automated workflows and field updates | Basic automation capabilities |
| Reporting | Enhance reporting features and insights | Basic reporting and tracking |
| Integration | Deeper integration with Issues and Pull Requests | Basic integration with repositories |
The configuration options for projects include creating a project, setting project descriptions and README, adding issues (including draft issues), creating custom fields (such as for tracking priority or iteration), grouping issues, saving views, adding board layouts, and configuring built-in automation workflows.
To create a project, users can choose between organization or user projects, then select a template or start from scratch.
Descriptions and READMEs can be added to communicate project purpose and instructions. Issues and pull requests can be added manually or through automation.
Custom fields like iteration and priority can be created to organize and track tasks effectively. Views can be saved and shared to maintain alignment on priorities. Board layouts can be utilized to visualize project progress based on status. Finally, built-in automation workflows can be configured to streamline project management tasks like auto-adding issues and setting statuses.
- Choose between organization or user project.
- Select project type or template.
- Enter project name and create.
- Navigate to your project settings.
- Add project description.
- Update project's README with relevant information.
- Paste issue or pull request URLs into the project.
- Press Return to add.
- Type draft issue idea and press Enter.
- Add body text if needed.
- Click on the rightmost field header and select "New field."
- Type field name and select "Iteration."
- Specify iteration duration and save.
- Click on the rightmost field header and select "New field."
- Type field name and select "Single select."
- Add priority options (High, Medium, Low) and save.
- Click on the view menu icon and select "Group."
- Choose "Priority" to group issues.
- Move issues between groups to change priority.
- Click on the view menu icon and select "Save changes."
- Share the URL with your team to maintain alignment.
- Click "New view" and select "Board" layout.
- Specify status for each issue.
- Save changes and give the view a descriptive name.
- Navigate to project workflows.
- Edit "Auto-add to project" workflow to filter items.
- Enable workflow to automatically add items.
- Add a workflow to set status to Todo when an item is added.
You have several options for adding issues and pull requests to your project.
Important
You can issues and pull requests to your project individually, automatically, or in bulk. When you add an issue or pull request to your project, an event will be added to the issue or pull request's timeline.
Furthermore, you can include issues and pull requests from any organization, and you also have the ability to add draft issues that can be converted into regular issues later on.
You can configure a built-in workflow to automatically add issues and pull requests from a repository when they meet specific filter criteria.
You can copy the URL of an issue or pull request into your clipboard and paste that into your project.
- Place your cursor in the bottom row of the project, next to the +.
- Paste the URL of the issue or pull request.
- To add the issue or pull request, press Return
If you know the issue or pull request number or if you know part of the title, you can search for an issue or pull request directly from your project.
- Place your cursor in the bottom row of the project, next to the +.
- To open the list of repositories, type #.
- Select the repository where the pull request or issue is located. You can type part of the repository name to narrow down your options.
- Select the issue or pull request. You can type part of the title to narrow down your options.
You can add multiple issues and pull requests from your project and use filters, such as label:bug, to narrow down your search.
- In the bottom row of the project, click +.
- Click Add item from repository.
- Optionally, to change the repository, click the dropdown and select a repository. You can also search for specific issues and pull requests.
- Select the issues and pull requests you want to add.
- Click Add selected items.
You can also add issues and pull requests to your project from a repository's issue and pull request lists.
- On GitHub.com, navigate to the repository that contains the issues or pull requests you want to add to your project.
- Under your repository name, click Issues or Pull requests.
- Select the issues or pull requests you want to add to your project.
- To select individual issues or pull requests, to the left of the title of each issue or pull request you want to add to your project, select the checkbox.
- To select every issue or pull request on the page, at the top of the list of issues or pull requests, select all.
- Above the list of issues or pull requests, click Projects.
- Click the projects you want to add the selected issues or pull requests to.
You can also add an issue or pull request to your project from within the issue or pull request itself.
- Navigate to the issue or pull request that you want to add to a project.
- In the side bar, click Projects.
- Select the project that you want to add the issue or pull request to.
- Optionally, populate the custom fields.
You can use the command palette when viewing your project to quickly add items.
- To open the project command palette, press Ctrl+K
- Start typing "Add items" and press Return.
- Optionally, to change the repository, click the dropdown and select a repository. You can also search for specific issues and pull requests.
- Select the issues and pull requests you want to add.
- Click Add selected items.
You can quickly create issues without leaving your project. When using a view that is grouped by a field, creating an issue in that group will automatically set the new issue's field to the group's value. For example, if you group your view by "Status", when you create an issue in the "Todo" group, the new issue's "Status" will automatically be set to "Todo."
- At the bottom of a table, group of items, or a column in board layout, click +.
- Click Create new issue.
- At the top of the "Create new issue" dialog, select the repository where you want the new issue to be created.
- Below the repository dropdown, type a title for the new issue.
- Optionally, use the fields below the title field to set assignees, labels, and milestones, and add the new issue to other projects.
- Optionally, type a description for your issue.
- Optionally, if you want to create more issues, select Create more and the dialog will reopen when you create your issue.
- Click Create.
Creating draft issues
Draft issues can have a title, text body, assignees, and any custom fields from your project. In order to populate the repository, labels, or milestones for a draft issue, you must first convert the draft issue to an issue.
Important
Draft issues are useful to quickly capture ideas. Unlike issues and pull requests that are referenced from your repositories, draft issues exist only in your project.
- Place your cursor in the bottom row of the project, next to the .
- Type your idea, then press Enter. 3.To add body text, click on the title of the draft issue. In the markdown input box that appears, enter the text for the draft issue body, then click Save.
You can use text fields to include notes or any other freeform text in your project.
Text fields can be used in filters, for example: field:"exact text". Text fields and item titles will also be used if you filter for text without specifying a field.
You can filter for date values using the YYYY-MM-DD format, for example: date:2022-07-01.
If your project makes use of date fields, you can use the roadmap layout to view items on a timeline.
You can create single select fields with multiple options, each with a description and a color, that can be selected from a dropdown menu.
You can filter by your single select fields by specifying the option, for example: fieldname:option.
You can filter for multiple values by providing a comma-separated list of options, for example: fieldname:option1,option2
Single select fields can contain up to 50 options.
You can create iterations to plan upcoming work and group items.
You can create an iteration field to associate items with specific repeating blocks of time.
Iterations can be set to any length of time, can include breaks, and can be individually edited to modify name and date range.
With projects, you can group by iteration to visualize the balance of upcoming work, use filters to focus on a single iteration, and sort by iteration.
When you first create an iteration field, three iterations are automatically created. You can add additional iterations and make other changes on your project's settings page.
If your project makes use of iteration fields, you can use the roadmap layout to view items on a timeline.
You can view the subtasks of the issues in your projects.
You can enable the Tracks and Tracked by fields on your projects to see the relationships between your issues as you add subtasks in tasklists.
The Tracked by field can be used to group items, creating a view that clearly shows the subtasks of each issue and the work required to complete them.
You can also filter by the Tracked by field to display only items that are tracked by specific issues. Either start typing "tracked-by" and select an issue from the list or, if you know the repository and issue number, you can type the filter below in full. For example: tracked-by:"<OWNER>/<REPO>#<ISSUE NUMBER>"
You can delete and rename your custom fields under your repo project settings.
You have differents options to automate your projects.
Warning
You must remember for the exam the following ones:
- Using the built-in automations: You can use built-in workflows to automate your projects.
- Using the API to manage Projects: You can use the GraphQL API to automate your projects.
- Automating Projects using Actions: You can use GitHub Actions to automate your projects.
- Adding items automatically You can configure your project's built-in workflows to automatically add items from repositories that match a filter.
- Archiving items automatically: You can configure your project's built-in workflows to automatically archive items that match a filter.
Github built-in Projects Workflows allow you to automate what happens based on specific events.
You can find them on the 3 dots button *** -> Worflows
Important
Remember this built-in options:
- Item added to project
- Item reopened
- Item closed
- Code changes requested
- Code review approved
- Pull request merged
- Auto-archive items
- Auto-add to projects
For more advanced automation of Github Projects you can use Github Actions
Projects insights lets you create charts about your Github Project
Important
Remember there are 2 types:
- Current Charts: Take a value and plot it (eg: how many items are assigned to each individuals)
- Historical Charts: Take a value and plot over time (eg: track changes to the state of your project items)
When commenting on an issues or pull request, you can add a saved reply that you've already set up
If you frequently add the same comment over and over, you can create a saved reply.
- In the upper-right corner of any page, click your profile photo, then click
Settings. - In the "Code, planning, and automation" section of the sidebar, click
Saved replies. - Under "Add a saved reply", add a title for your saved reply.
- In the "Write" field, add the content you'd like to use for the saved reply.
- To review your reply, click
Preview. - Click Add saved reply.
You can edit the title and body of a saved reply.
- In the upper-right corner of any page, click your profile photo, then click
Settings. - In the "Code, planning, and automation" section of the sidebar, click Saved replies.
- Under "Saved replies," next to the saved reply you want to edit, click Pencil Icon.
- Under "Edit saved reply," edit the title or content of the saved reply.
- Click Update saved reply.
If you find that you're no longer using a saved reply, you can delete it.
- In the upper-right corner of any page, click your profile photo, then click
Settings. - In the "Code, planning, and automation" section of the sidebar, click
Saved replies. - Under "Saved replies", next to the saved reply you want to delete, click X.
You can assign issues and pull requests to specific users.
And filter Issues and PR based on the assignees.