Automate GitHub Projects with Actions

Posted on 25/04/30 in Automation

GitHub Projects is a simple way to track work across repositories, but getting every new issue and pull request onto a central board without Enterprise features leaves you doing it by hand. That is exactly the kind of task that should be automated.

The approach

Add a small GitHub Actions workflow to each repository that sends newly opened issues and PRs to a single project board. Here is the workflow:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
name: Add to Project
# This GitHub Actions workflow automatically adds newly opened issues and pull requests to a specific GitHub project.

on:
  issues:
    types:
      - opened
      # Triggers the workflow when a new issue is opened in the repository.
  pull_request:
    types:
      - opened
      # Triggers the workflow when a new pull request is opened in the repository.

jobs:
  add-to-project:
    name: Add issue to project
    # Defines the job to add issues or pull requests to the specified GitHub project.

    runs-on: ubuntu-latest
    # Specifies the environment where the job will run. In this case, it uses the latest Ubuntu runner.

    steps:
      - uses: actions/add-to-project@v1.0.2
        # Uses the `actions/add-to-project` GitHub Action to add items to a GitHub project.
        # This action simplifies the process of adding issues or pull requests to a project board.

        with:
          project-url: https://github.com/users/joe-mccarthy/projects/4
          # The URL of the GitHub project where the issue or pull request should be added.
          # Replace this URL with the correct project URL for your repository.

          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
          # The GitHub personal access token (PAT) used to authenticate the action.
          # The token must have the necessary permissions to modify the specified project.
          # Store the token securely in the repository's secrets as `ADD_TO_PROJECT_PAT`.

It uses the actions/add-to-project action, listens to issues and pull_request events when they are opened, and targets your project via its URL. Authentication is via a repo secret named ADD_TO_PROJECT_PAT.

Token setup

Create a Personal Access Token with the appropriate scopes and store it as ADD_TO_PROJECT_PAT in each repo’s secrets.
Docs: GitHub Projects • Personal access tokens • Workflow syntax (all on docs.github.com)

What it delivers

All newly opened issues and PRs show up on the board automatically.
One place to scan the day’s work across multiple repositories.
No upgrade required to use the automation.

Optional extensions

Trigger on more events like issue_comment.
Route items to specific columns based on labels.
Filter to include only certain issues.

Simple file, big quality of life improvement.

Thanks for reading. If you have a neat column assignment pattern for Projects, share it so others can try it too.