the-events-calendar/gh-action-project-link

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

Much of this code was adapted from actions/add-to-project.

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

@TODO add examples

Inputs

• base-branch-pattern (optional) is a glob pattern to match the base branch name. If not provided, the action will match all base branches eg: release/* will match release/1.0, release/2.0, etc.
• name-prefix-remove (optional) Its a string to remove from the beginning of the base branch before searching for a project. If not provided, the action will use the base branch as is eg: release/ will remove release/ from release/Z24.kamehameha
• name-suffix-remove (optional) It is a string to remove from the end of the base branch before searching for a project. If not provided, the action will use the base branch as is eg: -hotfix will remove -hotfix from release/Z24.kamehameha-hotfix
• name-replace-with-spaces (optional) Its a colection of chars to replace with spaces in the base branch before searching for a project. If not provided, the action will use the base branch as is.
• template-project-url (optional) is the URL of the project to use as a template for the new project. If not provided, the action will create a new project _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 pull_request events:

• opened
• reopened
• labeled

Using these events ensure that a given 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 with project scope. For private repos you will also need repo scope. See Creating a personal access token for more information

  NOTE: ℹ️ Use a classic token with full control of projects. Personal access tokens with fine grained access do not support the GraphQL API.

• 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 Project Link 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 20.x, so we recommend using that version of Node (see "engines" in this action's package.json for details).

> git clone https://github.com/the-events-calendar/gh-action-project-link
> cd gh-action-project-link
> 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