Add issues to projects on GitHub#

Adding issues to projects on GitHub is a great way to keep track of what needs to be done. This action will add issues to a project board on GitHub when they are opened or labeled. But adding issues to a project board is a manual process. The action actions/add-to-project automates the process of adding issues to a project board.

Setting up GitHub#

In the workflows the environment variable ADD_TO_PROJECT_URL is used to define the project board. The project board is defined by the URL of the project board. The URL can be found in the browser when the project board is opened. The URL is defined in the env section of the workflow file.

The workflow also requires a personal access token (PAT) to authenticate with GitHub. The PAT is defined in the secrets section for Actions of the repository. The PAT is defined in the github-token input of the action.

Setting the PAT for GitHub Actions

If the repository also depends on DependaBot, then the workflow also requires a PAT to authenticate with GitHub. The PAT is defined in the secrets section for DependaBot of the repository. The PAT is defined in the github-token input of the action.

Setting the PAT for DependaBot

Adding issues#

The following workflow is triggered when an issues is opened and will add issues to a project board when they’re opened and it will use the labels on the issue to determine if it should be added to the project board. The labels are defined in the labeled input and the operator is defined in the label-operator input. The operator can be one of the following: OR, AND, or NOT.

Workflow file .github/workflows/add-to-project.yml for GitHub Actions#
 1---
 2name: Add to project board
 3
 4on:
 5  issues:
 6    types:
 7      - opened
 8
 9env:
10    ADD_TO_PROJECT_URL: https://github.com/users/acme/projects/1
11
12jobs:
13  add-to-project:
14    name: Add issue to project
15    runs-on: ubuntu-latest
16    steps:
17      - uses: actions/[email protected]
18        with:
19          project-url: ${{ env.ADD_TO_PROJECT_URL }}
20          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
21          labeled: bugs, enhancement, policy, project, security, stale
22          label-operator: OR

Adding pull-requests#

The workflow can also be triggered when a pull-request is labeled. This is different from the previous workflow as that workflow only was triggered when an issue was opened. The rest of the workflow is the same as the previous workflow, but the labeled section is different.

Workflow file .github/workflows/add-to-project.yml for GitHub Actions#
 1---
 2name: Add to project board
 3
 4on:
 5  pull_request:
 6    types:
 7      - labeled
 8
 9env:
10    ADD_TO_PROJECT_URL: https://github.com/users/acme/projects/1
11
12jobs:
13  add-to-project:
14    name: Add issue to project
15    runs-on: ubuntu-latest
16    steps:
17      - uses: actions/[email protected]
18        with:
19          project-url: ${{ env.ADD_TO_PROJECT_URL }}
20          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
21          labeled: dependencies, stale
22          label-operator: OR

Until now the label-operator was OR, but now it’s AND in the next examepl. This means that the issue will only be added to the project board if it has both the github and policy labels.

Workflow file .github/workflows/add-to-project.yml for GitHub Actions#
 1---
 2name: Add to project board
 3
 4on:
 5  pull_request:
 6    types:
 7      - labeled
 8
 9env:
10    ADD_TO_PROJECT_URL: https://github.com/users/acme/projects/1
11
12jobs:
13  add-to-project:
14    name: Add issue to project
15    runs-on: ubuntu-latest
16    steps:
17      - uses: actions/[email protected]
18        with:
19          project-url: ${{ env.ADD_TO_PROJECT_URL }}
20          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
21          labeled: github, policy
22          label-operator: AND

Combining issues and pull-requests#

In the previous example the workflow was triggered when an issue was opened and when a pull-request was labeled. But the workflow can also be triggered when an issue is labeled and when a pull-request is opened. Secondly it can have multiple steps to select the labels and the operator to add issues and pull-request to the project board.

Note

Currently this action supports the following issues events:

  • opened

  • transferred

  • labeled

and the following pull_request events:

  • opened

  • labeled

Combining issues and pull-requests to a single workflow with multiple steps to add issues and pull-requests to a project board is shown in the following example. It will add issues to a project board when they are opened and labeled. It will also add pull-requests to a project board when they are labeled. This allows for more flexibility in the workflow and selecting the labels and the operator to add issues and pull-requests to the project board.

Workflow file .github/workflows/add-to-project.yml for GitHub Actions#
 1---
 2name: Add to project board
 3
 4on:
 5  issues:
 6    types:
 7      - opened
 8      - labeled
 9  pull_request:
10    types:
11      - labeled
12
13env:
14    ADD_TO_PROJECT_URL: https://github.com/users/acme/projects/1
15
16jobs:
17  add-to-project:
18    name: Add issue to project
19    runs-on: ubuntu-latest
20    steps:
21      - uses: actions/[email protected]
22        with:
23          project-url: ${{ env.ADD_TO_PROJECT_URL }}
24          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
25          labeled: bugs, enhancement, policy, project, security, stale
26          label-operator: OR
27
28      - uses: actions/[email protected]
29        with:
30          project-url: ${{ env.ADD_TO_PROJECT_URL }}
31          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
32          labeled: dependencies, stale
33          label-operator: OR
34
35      - uses: actions/[email protected]
36        with:
37          project-url: ${{ env.ADD_TO_PROJECT_URL }}
38          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
39          labeled: github, policy
40          label-operator: AND

Note

This workflow is based on the actions/add-to-project action, but GitHub has since added the ability to add issues to a project board automatically and is in beta for now together with automatically archiving project items.