Arkaive

Project Board Workflow

Table of Contents

Setting up the project board

In the repository, go to Projects and click the green + New project button.
Here, select Team planning, the first option.


And then I enable Bulk import items, which ensures that issues created in the repository’s Issues tab are automatically added to the project board.

Columns

After creating the project board, I find it useful to immediately set up all columns and adjust their descriptions.

Issues – Project Board Fields

In each issue, you can find several fields on the right-hand side. These fields are also reflected in the project board.
image

Customizing These Fields

In the top-right corner, click the three dots and then Settings.
image

Visible Fields

In the project board, you can see which fields are selected for that issues. I find the default layout unclear, so I customize it via View → Fields:
image

The fields I keep visible are:

The order of these fields determines how they appear in the issue view. (drag and drop to youyr preference)

Labels

How to create or modify labels:
open an issue → click the settings icon next to Labels → Then click Edit labels at the bottom
By default, a bug label already exists, so I do not change anything here.

I usually do not work with labels. With labels, you can add multiple values to a single issue, such as multiple MoSCoW priorities or multiple sizes.
In the fields that we adjusted earlier, only one option can be selected by default. Selecting multiple options is not possible, and when you change the value, it is updated rather than added.

Type

In my FDND agency project from semester 3, there was a field called Type.
This field was used to indicate what kind of issue it was, for example an epic, feature, or task.
It is similar to labels, but only one option can be selected.
The Type field does not exist by default in GitHub Projects, you need to create it yourself.

In Project settings (the three dots in the top right corner of the project board → Settings),
you can create custom fields by clicking the + button.
image

I named the field Type,
set the field type to Single select,
and created the following options:

Issue Templates

To ensure that issues are written clearly and consistently, you can create issue templates that help guide users when creating an issue.
In your repository settings, under Issues:
image
image
GitHub provides default templates, but you can also create custom templates tailored to your project.

You can also create a .github/ISSUE_TEMPLATE folder in the root of your project and write all your issue templates there.
After that, you can push them to GitHub.

After creating the issue templates, GitHub automatically shows all available issue template options when you create a new issue. You can then select the appropriate template and fill in the required information.

Branches

When creating a branch, I prefer to start from the issue.
In the right hand column of the issue, you can find the option to create a branch, which is then automatically linked to that issue.
This also ensures a consistent branch naming convention by including the issue number and issue title
image

You can click Create branch and follow the steps in the popup to create a new branch.
By selecting Checkout locally, GitHub provides the terminal commands that you can copy and paste into the terminal of your project directory.
You can also use GitHub Desktop. Both options are convenient because the branch is created for you and you are automatically switched to that branch.

Pull Request Template

In the .github/ folder, you can also create pull request templates.
The file must be named PULL_REQUEST_TEMPLATE.md
Just like with issues, the contents of this template are automatically shown when a pull request is created.

Charts

When you click Insights in the top-right corner of the project board, you can access the charts view.

Some charts, such as the burn-up chart, are available by default, but you can also create custom charts.
What’s important when creating charts is that they use the fields we just created and customized, as these fields determine what data can be visualized.

I don’t have enough "data" in my project board to experiment with this. I’ll come back to it after a few sprints.

Automations

With workflows, you can configure what your project board does automatically:
image

Editing Default Workflows

Auto add to project

By default, only open issues are added to the project board: is:issue is:open
By adding pull requests to the filter, PRs will also be added to the project board: is:issue,pr is:open

Item added to project

Issues and pull requests are now added to the project board, but by default they are placed in a New column with the status No status.

In the workflow Item added to project, you can change this behavior.
If you change the Set value field to Backlog, newly created issues and PRs will automatically be placed in the Backlog instead of ending up in a No status column on the project board.

Pull request linked to issue

I was stuck on this for quite a while.

I wanted pull requests to be automatically moved to the Review column, but all the examples I found online used either GitHub Actions or additional / duplicate workflows.

However, on the free GitHub plan there is a limited number of workflows available, so I couldn’t use those options.

I then took another look at the default workflows and noticed that I wasn’t really using Auto close issue. That workflow automatically closes an issue when it is dragged to the Done column. I don’t use this flow, I always close issues manually from the issue page instead of dragging them to Done.

So I thought: I’ve disabled a workflow, which means I should now be able to create a duplicate one. Unfortunately, that’s not how it works.

After that, I noticed the Pull request linked to issue workflow. When you create a PR from an issue using Create a branch, this workflow allows you to move the issue to a different column when the PR is created.

In this workflow, I changed the Set value to Review. Now, the issue is automatically moved to the Review column as soon as a PR is created, without using GitHub Actions.

Note: this only moves the issue, not the PR itself. The PR will still remain in the Backlog.
Which is not what I originally wanted, but good enough. Also, the issue stays in its current column until you create a PR for the branch, which is ideal because it allows the issue to remain in In Progress while you’re still working on the branch.

If you didn’t create the PR from the issue, you can still link it afterward by adding the PR to the issue manually: