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/github-project-automation-plus@v0.8.3
        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/github-project-automation-plus@v0.8.3
        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.

Create a personal access token
Add a secret GHPROJECT_TOKEN with the personal access token.
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

alex-page / github-project-automation-plus