Automate GitHub Projects with Actions

Posted on 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:

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.