To use the action, create a workflow that runs when issues are opened in your repository. Run this action in a step, optionally configuring any filters you may want to add, such as only adding issues with certain labels.

name: Add bugs to bugs project

on:
  issues:
    types:
      - opened

jobs:
  add-to-project:
    name: Add issue to project
    runs-on: ubuntu-latest
    steps:
      - uses: actions/add-to-project@main
        with:
          project-url: https://github.com/orgs/<orgName>/projects/<projectNumber>
          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
          labeled: bug

Inputs

project-url (required) is the URL of the GitHub Project to add issues to.
eg: https://github.com/orgs|users/<ownerName>/projects/<projectNumber>
github-token (required) is a personal access token with the repo, write:org and read:org scopes.
See Creating a PAT and adding it to your repository for more details
labeled (optional) is a comma-separated list of labels used to filter applicable issues. When this key is provided, an issue must have one of the labels in the list to be added to the project. Omitting this key means that any issue will be added.

Supported Events

Currently this action supports the following issue events:

opened
transferred
labeled

This ensures that all issues in the workflow's repo are added to the specified project. If labeled input(s) are defined, then issues will only be added if they contain at least one of the labels in the list.

How to point the action to a specific branch or commit sha

Pointing to a branch name generally isn't the safest way to refer to an action, but this is how you can use this action now before we've begun creating releases.

jobs:
  add-to-project:
    name: Add issue to project
    runs-on: ubuntu-latest
    steps:
      - uses: actions/add-to-project@main
        with:
          project-url: https://github.com/orgs/<orgName>/projects/<projectNumber>
          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}

Another option would be to point to a full commit SHA:

jobs:
  add-to-project:
    name: Add issue to project
    runs-on: ubuntu-latest
    steps:
      - uses: actions/add-to-project@<commitSHA>
        with:
          project-url: https://github.com/orgs/<orgName>/projects/<projectNumber>
          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}

Creating a PAT and adding it to your repository

create a new personal access token with repo, write:org and read:org scopes
See Creating a personal access token for more information
add the newly created PAT as a repository secret, this secret will be referenced by the github-token input
See Encrypted secrets for more information

Development

To get started contributing to this project, clone it and install dependencies. Note that this action runs in Node.js 16.x, so we recommend using that version of Node (see "engines" in this action's package.json for details).

> git clone https://github.com/actions/add-to-project
> cd add-to-project
> npm install

Or, use GitHub Codespaces.

See the toolkit documentation for the various packages used in building this action.

Publish to a distribution branch

Actions are run from GitHub repositories, so we check in the packaged action in the "dist/" directory.

> npm run build
> git add lib dist
> git commit -a -m "Build and package"
> git push origin releases/v1

Now, a release can be created from the branch containing the built action.

License

The scripts and documentation in this project are released under the MIT License

README.md

actions/add-to-project

Current Status

Usage

Further reading and additional resources