GitHub Project Automation+

🤖 Automate GitHub Project cards with any webhook event

This action allows you to use any of the pull_request and issue webhook events to automate your project cards. For example when an issue is opened create a card in the Backlog project, Triage column.

If the pull_request or issue card already exists it will be moved to the column provided. Otherwise the card will be created in the column.

Usage

Create a project with columns in your repository, user profile or organisation.

Create a new workflow .yml file in the .github/workflows/ directory. In the .ymlfile you have to decide what webhook events going move or create a card in a column. For more detailed explanation of the workflow file, check out the GitHub documentation. See the examples below to get started quickly.

.github/workflows/opened-issues-triage.yml

Move opened issues into the Triage column of the Backlog project

name: Move new issues into Triage

on:
  issues:
    types: [opened]

jobs:
  automate-project-columns:
    runs-on: ubuntu-latest
    steps:
      - uses: alex-page/[email protected]
        with:
          project: Backlog
          column: Triage
          repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/assigned-pulls-todo.yml

Add assigned pull requests into the To Do column of the Backlog project

name: Move assigned pull requests into To do

on:
  pull_request:
    types: [assigned]

jobs:
  automate-project-columns:
    runs-on: ubuntu-latest
    steps:
      - uses: alex-page/[email protected]
        with:
          project: Backlog
          column: To do
          repo-token: ${{ secrets.GITHUB_TOKEN }}

Workflow options

Change these options in the workflow .yml file to meet your GitHub project needs.

Inputs	Description	Values
on	When the automation is ran	issues pull_request issue_comment pull_request_target pull_request_review
types	The types of activity that will trigger a workflow run.	opened, assigned, edited: See GitHub docs for more
project	The name of the project	Backlog
column	The column to create or move the card to	Triage
repo-token	The personal access token	${{ secrets.GITHUB_TOKEN }}
action	This determines the type of the action to be performed on the card, Default: update	update, delete, archive, add

Personal access token

Most of the time GITHUB_TOKEN will work as your repo-token. This requires no set up. If you have a public project board and public repository this is the option for you.

Repository project, private repository or organisation projects

You will need a personal access token to send events from your issues and pull requests.

1. Create a personal access token

   1. Public repository and repository project
   2. Private repository or private project
   3. Organisation project board or organisation repository

2. Add a secret GHPROJECT_TOKEN with the personal access token.

3. Update the repo-token in the workflow .yml to reference your new token name:

repo-token: ${{ secrets.GHPROJECT_TOKEN }}

Troubleshooting

GraphqlError: Resource not accessible by integration or Secrets are not currently available to forks.

This error happens on repository projects and forked repositories because GITHUB_TOKEN only has read permissions. Create a personal access token following the instructions above.

Parameter token or opts.auth is required

This error happens when using a personal access token to run the workflow on PRs from forked repositories. This is because GitHub secrets are not populated for workflows triggered by forks. Use pull_request_target as the webhook event instead to enable access to secrets.

SAML enforcement

With certain organisations there may be SAML enforcement. This means you will need to Enable SSO when you create the personal access token.

GraphqlError: Resource protected by organization SAML enforcement. You must grant your personal token access to this organization

Can't read repository null

Make sure your permissions for your personal access token are correctly configured. Follow the above guide on permissions.

Private repositories

You may need to enable policy settings to allow running workflows from forks. Please refer to GitHub's documentation to learn about enabling these settings at enterprise, organization, or repository level.

Release History

• v0.8.3 - Update documentation so users get latest version
• v0.8.2 - Update NodeJS support to use latest version
• v0.8.1 - Fix issue_coment error with automation
• v0.8.0 - Add new action type add
• v0.7.1 - Move Node.js version back to v12
• v0.7.0 - Update documentation and dependencies
• v0.6.0 - Add support for pull_request_target and pull_request_review
• v0.5.1 - Fix get event data from issue_coment
• v0.5.0 - Add option to delete card
• v0.4.0 - Add issue_comment event
• v0.3.0 - Add pull_request_target event
• v0.2.4 - Update dependencies
• v0.2.3 - Replace reserved secret GITHUB_TOKEN with GITHUB_TOKEN in documentation
• v0.2.2 - Refactor add and move card logic ✨
• v0.2.1 - Fix bug with move logic when card is already in project
• v0.2.0 - Restructure project, add tests, change add and move logic
• v0.1.3 - Exact match for project names
• v0.1.2 - Fix action not running for a card that exists in multiple projects
• v0.1.1 - Document type filter so action runs once
• v0.1.0 - Add support for user projects
• v0.0.3 - Automatic build before commit
• v0.0.2 - Error handling using GitHub actions
• v0.0.1 - Update icon and color for GitHub actions
• v0.0.0 - Initial release