GitHub Project Board

In order to ease up the burden of the project maintainers, there is an internal Project Board on GitHub used to track the progress of the PRs and issues. The board is available only to the @GersonRS/is-modern-gitops-stack team and is available here. All the repositories of the Modern Gitops Stack are also connected to this project upon creation.

The way this is accomplished is somewhat convoluted, hence the reason for this documentation page.

Modern Gitops Stack Project

The project itself has been manually created on the @GersonRS organization, using the GitHub web interface (documentation). The project is private (documentation) and only accessible to the @GersonRS/is-modern-gitops-stack team (documentation).

All the boards and tables have also been created manually. In the settings of the project, there are automation workflows (documentation) that move the Issues and PRs around depending on their status (open, closed, merged, etc.).

Adding a PR/Issue to the Project

Since there are some limits on how many repositories we can add to a project using the default workflows, we were forced to automate this process using a GitHub workflow, as suggested on the official documentation.

Although the official documentation explicitly calls the API with gh commands, we opted to use an official GitHub Action (actions/add-to-project) to accomplish this. Moreover, in order to allow the workflows to modify the project we needed to create a GitHub app that the sole purpose is providing the necessary permissions to the workflows.

Modern Gitops Stack Project App

The app is called Modern Gitops Stack Project and is available here.

This app was created on our organization by an administrator and is configured with a limited scope of permissions: it can only access the projects of the organization where it is installed as well as the PRs and Issues of repositories on which it is installed (official documentation on how to create a GitHub app).

After the app creation, an administrator was needed to install it on the organization and all the repositories of the Modern Gitops Stack. This was done by going to the app page and clicking on the Install button then configuring the proper settings after installation (all this is done on the organization settings, check the official documentation).

The reason to not install the app on all the repositories by default was to further limit the scope of the app, although this adds the burden of installing it on each repository manually every time a new repository of the Modern Gitops Stack is created.

Centralized workflow

The workflow definition is available in the main repository.

---
# GitHub Actions workflow to automatically push PRs and issues to the Modern Gitops Stack project board.
#
# IMPORTANT: This workflow is called by other workflows in our Modern Gitops Stack repositories and it is centralized here in
# order to be easily maintained across modules. Because of this, please make sure you're not introducing any breaking
# changes when modifying this workflow.

name: "pr-issues-project"

on:
  workflow_call:
    secrets:
      PROJECT_APP_PRIVATE_KEY:
        description: "GitHub App private key for the Modern Gitops Stack Project app"
        required: true

  issues:
    types:
      - opened
      - reopened

  pull_request:
    types:
      - opened
      - reopened

jobs:
  add-to-project:
    runs-on: ubuntu-latest
    steps:
      - name: Generate authentication token from GitHub App
        id: generate_token
        uses: actions/create-github-app-token@v1
        with:
          app-id: 882683
          private-key: ${{ secrets.PROJECT_APP_PRIVATE_KEY }}

      - name: Add PR or issue to Modern GitOps Stack project board
        uses: actions/add-to-project@v1.0.1
        with:
          project-url: https://github.com/users/GersonRS/projects/2
          github-token: ${{ secrets.GITHUB_TOKEN }}
          labeled: bug, needs-triage
          label-operator: NOT

It is the step Generate authentication token from GitHub App that uses the GitHub app created above in order to generate a token with the proper permissions that is then passed to the Add PR or issue to Modern Gitops Stack project board step.