actions/add-to-project

Use this action to automatically add the current issue or pull request to a GitHub project. Note that this action does not support GitHub projects (classic).

Current Status

Usage

See action.yml for metadata that defines the inputs, outputs, and runs configuration for this action.

For more information about workflows, see Using workflows.

Create a workflow that runs when Issues or Pull Requests are opened or labeled in your repository; this workflow also supports adding Issues to your project which are transferred into your repository. Optionally configure any filters you may want to add, such as only adding issues with certain labels. You may match labels with an AND or an OR operator, or exclude labels with a NOT operator.

Once you've configured your workflow, save it as a .yml file in your target Repository's .github/workflows directory.

Examples

Example Usage: Issue opened with labels bug OR needs-triage

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@RELEASE_VERSION
        with:
          # You can target a project in a different organization
          # to the issue
          project-url: https://github.com/orgs/<orgName>/projects/<projectNumber>
          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
          labeled: bug, needs-triage
          label-operator: OR

Example Usage: Adds all issues opened that do not include the label bug OR needs-triage

name: Adds all issues that don't include the 'bug' or 'needs-triage' labels to project board

on:
  issues:
    types:
      - opened

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

Example Usage: Pull Requests labeled with needs-review and size/XL

name: Add needs-review and size/XL pull requests to projects

on:
  pull_request:
    types:
      - labeled

jobs:
  add-to-project:
    name: Add pull request to project
    runs-on: ubuntu-latest
    steps:
      - uses: actions/add-to-project@RELEASE_VERSION
        with:
          project-url: https://github.com/orgs/<orgName>/projects/<projectNumber>
          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
          labeled: needs-review, size/XL
          label-operator: AND

Further reading and additional resources

• actions/add-to-project
  • Current Status
  • Usage
    • Examples
      • Example Usage: Issue opened with labels bug OR needs-triage
      • Example Usage: Adds all issues opened that do not include the label bug OR needs-triage
      • Example Usage: Pull Requests labeled with needs-review and size/XL
    • Further reading and additional resources
  • Inputs
  • Supported Events
  • Creating a PAT and adding it to your repository
  • Setting a specific status or column name to the project item
  • Development
    • Building dist/
  • Releasing
  • License

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 repo and project 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.
• label-operator (optional) is the behavior of the labels filter, either AND, OR or NOT that controls if the issue should be matched with all labeled input or any of them, default is OR.

Supported Events

Currently this action supports the following issues events:

• opened
• reopened
• transferred
• labeled

and the following pull_request events:

• opened
• reopened
• labeled

Using these events ensure that a given issue or pull request, in the workflow's repo, is 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.

Creating a PAT and adding it to your repository

• Create a new personal access token. See Creating a personal access token for more information

  • For Tokens (classic) include the project scope; for private repos you will also need repo scope.
  • For Fine-grained tokens, you must first select the appropriate owner and associated repositories. Then select Organization permissions -> projects read & write, and Repository permissions -> issues read-only and pull requests read-only.

• 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

Setting a specific status or column name to the project item

If you want to add an issue to a custom default column in a project (i.e. other than 'Todo'), you can do this directly via the project UI. You don't need to add anything else to your YAML workflow file to get this to work.

Use the Add To GitHub Projects action to assign newly opened issues to the project. And then in the project UI simply specify which column to use as the default!

Development

To get started contributing to this project, clone it and install dependencies. Note that this action runs in Node.js 24.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 ci

Or, use GitHub Codespaces.

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

Building dist/

This action's compiled output is committed to dist/, and the check-dist workflow fails if dist/ doesn't match a fresh build. Rebuild and commit dist/ as part of your pull request whenever you change anything the bundle is built from — most commonly src/, but also fix-regex.js, tsconfig.json, or dependencies in package.json / package-lock.json:

npm ci
npm run build
git add dist/

npm run build formats, runs the type/format/lint checks, compiles, and packages, so it catches problems before CI does. If you only want the bundle, run npm run build:compile and npm run build:package — that pair is exactly what check-dist runs.

A few things worth knowing:

• Run npm ci, not npm install, before rebuilding. npm ci installs exactly what package-lock.json specifies. If node_modules has drifted from the lockfile — most commonly after a dependency bump lands on main — the bundle you commit will differ from the one CI builds, and check-dist will fail with a diff in code you never touched.
• check-dist ignores Markdown-only pull requests, so a green run on a docs change doesn't mean dist/ is current.
• If check-dist fails, read the diff it prints. It also uploads the expected dist/ as a workflow artifact, which you can download and compare against your local build.

Releasing

This project uses semantic-release to automate versioning and GitHub Releases. When a pull request is merged to main, the release workflow analyzes commit messages and—if a release is warranted—creates a new version tag, publishes a GitHub Release, and updates the major version tag (e.g., v2) to point to the latest release.

Commit messages must follow Conventional Commits:

• fix: ... → patch release
• feat: ... → minor release
• BREAKING CHANGE in footer → major release

See RELEASING.md for full details on commit format, troubleshooting, and how the release process works.

License

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