How to maintain automated Workflows for GitHub Issues and PRs

This page is directed at persons trying to maintain the IssueProject.yml and/or InDiscussionProject.yml workflow files responsible for automatically adding and moving issues and pull requests in the Issues project.

Authentication

Certain actions used by workflows require write access e.g. to projects. In this case, secrets.GITHUB_TOKEN is not viable, due to it only granting access to the current repository the workflow is run in.

The current method of authentication is GitHub Personal Access Tokens, their drawback is that they are linked to a person's GitHub account and their permissions in this organization.

Creating a Personal Access Token & Adding it to the Organization

1. Create a new Personal Access Token in the settings of your account here

   • Usually a Token (classic) is expected, but depending on the exact Action a Fine-grained token might also be suitable
   1. Set the name and expiration. As soon as the token expires, the workflow is broken until a new valid token is stored
   2. Depending on the Action and its required permissions, certain scopes have to be selected
   3. Copy the created string representing the Personal Access Token. It should start with ghp_

2. Store this token in this organization as a secret here

   • This link might redirect you to a 404 page depending on your access in the organization. At least an admin access is required.
   1. Set the name. This can then be accessed using e.g. secrets.MY_PERSONAL_ACCESS_TOKEN
   2. For the large Value field, insert the token previously copied in 1.3.
   3. Depending on the repositories the token will be used in, under Repository access its use can be limited to said repositories.

3. Integrate the Personal Access Token into the workflow.yml files using the name defined in 2.1

IssueProject.yml - Adding new Issues & PRs to the Issues Project

The lines github-token: ${{ secrets.OEO_WORKFLOWS }} have to contain a reference to a valid Personal Access Token. As described here in the README of the used action, the following token scopes are required:

• 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.