Automating Projects using Actions

GitHub Actions workflows

This article demonstrates how to use the GraphQL API and GitHub Actions to add a pull request to an organization project. In the example workflows, when the pull request is marked as "ready for review", a new task is added to the project with a "Status" field set to "Todo", and the current date is added to a custom "Date posted" field.

You can copy one of the workflows below and modify it as described in the table below to meet your needs.

A project can span multiple repositories, but a workflow is specific to a repository. Add the workflow to each repository that you want your project to track. For more information about creating workflow files, see Quickstart for GitHub Actions.

This article assumes that you have a basic understanding of GitHub Actions. For more information about GitHub Actions, see GitHub Actions documentation.

For more information about other changes you can make to your project through the API, see Using the API to manage Projects.

You may also want to use the actions/add-to-project workflow, which is maintained by GitHub and will add the current issue or pull request to the project specified. For more information, see the actions/add-to-project repository and README.

For project management tasks that require understanding repository context—such as triaging new issues, summarizing backlogs, classifying issues by type or priority, and recommending field values—agentic workflows are a better fit than traditional GitHub Actions workflows. Unlike fixed workflow steps, agentic workflows let you describe what you want in natural language, and an AI coding agent handles the reasoning and decision-making. For more information, see Creating GitHub Agentic Workflows.

Example workflow authenticating with a GitHub App

For more information about authenticating in a GitHub Actions workflow with a GitHub App, see Making authenticated API requests with a GitHub App in a GitHub Actions workflow.

1. Create a GitHub App or choose an existing GitHub App owned by your organization. For more information, see Registering a GitHub App.

2. Give your GitHub App read and write permissions to organization projects. For this specific example, your GitHub App will also need read permissions to repository pull requests and repository issues. For more information, see Modifying a GitHub App registration.

   Note

   You can control your app's permission to organization projects and to repository projects. You must give permission to read and write organization projects; permission to read and write repository projects will not be sufficient.

3. Install the GitHub App in your organization. Install it for all repositories that your project needs to access. For more information, see Installing your own GitHub App.

4. Store your GitHub App's client ID as a configuration variable in your repository or organization. In the following workflow, replace APP_CLIENT_ID with the name of the configuration variable. You can find your client ID on the settings page for your app or through the App API. For more information, see REST API endpoints for apps. For more information about configuration variables, see Store information in variables.

5. Generate a private key for your app. Store the contents of the resulting file as a secret in your repository or organization. (Store the entire contents of the file, including -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----.) In the following workflow, replace APP_PRIVATE_KEY with the name of the secret. For more information, see Managing private keys for GitHub Apps. For more information about storing secrets, see Using secrets in GitHub Actions.

6. In the following workflow, replace