GitHub add to Projects Automation

Why GitHub Projects?

I’ve been a fan of GitHub Projects¹ for years now. It’s a simple, effective way to track tasks across repositories, and it integrates naturally with the GitHub ecosystem I’m already living in. For someone like me who manages multiple personal projects across different repositories, having everything organized in one place is a game-changer.

But there’s a catch.

If you want issues and pull requests from all your repositories to automatically appear in your project board, GitHub nudges you toward their Enterprise tier. Not exactly budget-friendly for a solo developer or small team.

The Problem: Manual Work is Still Work

I use my GitHub project board as my daily to-do list for personal repositories. Manually adding every new issue and pull request to the board isn’t just tedious—it’s exactly the kind of repetitive task that should be automated.

What I needed was a way to ensure both public AND private repositories would automatically add their issues and PRs to my central project board, without having to pay for features I don’t need.

The Solution: GitHub Actions to the Rescue

After some digging (and a late night of caffeine-fueled experimentation), I found that GitHub Actions could solve this elegantly. By adding a simple workflow file to each repository, I could automate the process of adding new issues and PRs to my central project board.

Here’s the workflow file I use:

 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`.

How It Works

The workflow is surprisingly straightforward (I was honestly expecting more complexity):

1. Event Triggers: The workflow kicks in whenever someone opens a new issue or creates a pull request.

2. Simple Job: It runs a single job that uses the actions/add-to-project action to add the new item to my project board. No fuss.

3. Configuration: I just need to specify my project URL and provide a Personal Access Token with the right permissions.

Setting Up Your Personal Access Token

For this workflow to function properly, you’ll need to create a Personal Access Token (PAT) with appropriate permissions:

1. Go to GitHub Settings → Developer settings → Personal access tokens².
   • Click on “Tokens (classic)” and then “Generate new token.”
2. Generate a new token with at least the following scopes:
   • repo (for accessing repositories)
   • project (for modifying project boards)
3. Add this token as a repository secret named ADD_TO_PROJECT_PAT

Implementation Across Multiple Repositories

The beauty of this approach is its scalability. I’ve added this workflow file to all my active repositories, both public and private. Since each repository runs its own GitHub Actions workflows, they can all independently add their issues and PRs to my central project board.

I’ll be honest - the first time I saw it all working together, with issues from five different repos automatically appearing in my project board, I did a little happy dance in my office. It’s the small wins, right?

Benefits I’ve Seen

After implementing this workflow across my repositories, I’ve noticed several improvements:

1. Complete Visibility: All my tasks from different repositories appear in one place without manual intervention. No more “oh crap, I forgot about that issue I opened last week.”

2. No More Forgotten Tasks: Every new issue automatically shows up in my to-do list, so nothing slips through the cracks. My goldfish memory is finally not a liability!

3. Cost Efficiency: I get the automatic organization I need without upgrading to a more expensive GitHub plan. Sorry GitHub, you’ll have to try harder to get my credit card details.

Potential Improvements

This basic workflow does exactly what I need, but there are some ways you could extend it:

• Add more event types like issue_comment to track activity³
• Create custom logic to assign items to specific columns based on labels
• Add filtering logic to only include certain issues based on criteria

I haven’t felt the need to add these bells and whistles yet, but they’re there if you want to get fancy.

Conclusion

GitHub Projects is a powerful tool for organizing work, and with this simple automation workflow, you can get enterprise-like features without the enterprise price tag. It’s made my daily workflow much smoother, keeping all my tasks organized across multiple repositories with zero manual effort.

The best part? It’s just a simple YAML file that you can copy, paste, and adapt to your own workflow needs. Sometimes the simplest solutions really are the best.