Project Status Sync

Project Status Sync (GitHub App + IssueOps)

This page documents how our project-status.yml workflow works at the org level, how the GitHub App that powers it was created, and how to maintain or update it.
It supports automatic status transitions on our org-wide project board (Project #14).

---

Overview

This automation is powered by:

Component	Purpose
GitHub App	Provides a secure, short-lived org token for automation
Project Status Workflow	Sets the correct board status for Issues and Pull Requests
Project v2 GraphQL API	Allows updating Status fields programmatically

The workflow cannot run with personal tokens and cannot run with standard repo secrets — it requires a GitHub App with org-level permissions.

---

GitHub App Setup

The app must be created at the organization level, not per-repo.

Required App Permissions

Category	Permission
Repository Permissions	Contents: Read, Metadata: Read
Organization Permissions	Projects: Read/Write, Members: Read
User Permissions	None required

The critical permission is Org Projects: Read/Write, which is required to update Project v2 fields.

Webhook Requirements

The GitHub App does not need a webhook URL for this workflow.
It is used only to generate tokens for GitHub Actions.

Install the App

After creation, install it to the entire organization.
This gives the app access to read/write our shared org project board.

---

Required Repository Configuration

Each repo using this automation must define:

1) Secret

Secret Name	What It Stores
APP_PEM	PEM private key downloaded from the GitHub App

Only owners or approved maintainers should add this secret.

2) Variable

Variable Name	What It Stores
APP_ID	The GitHub App’s numeric ID (found on app settings page)

This is a variable, not a secret — it is not sensitive.

3) Project Number

The workflow references our org board:

Variable	Value
PROJECT_NUMBER	14

We do not store this as a secret or variable yet — board number is hardcoded and may be changed later.

---

How the Workflow Uses the App

A short-lived authentication token is created with:

uses: actions/create-github-app-token@v2

This produces a token valid for about 10 minutes.
It grants permission to update Project v2 fields securely.

GraphQL API calls are then executed using:

gh api graphql

These calls:

• Fetch project/field IDs
• Add/remove items
• Update Status field values

If authentication fails, no project updates are possible, which is expected behavior.

---

Status Logic (How Status Changes Work)

The workflow listens for:

Event Type	Examples
Issue Events	opened, assigned, closed, reopened
Pull Request Events	opened, ready, draft, closed, merged
Review Events	changes requested

It translates these into board statuses:

Event	Status
Issue opened	Backlog
Issue assigned	In Progress
PR opened (not draft)	In Review
PR draft created or re-drafted	In Progress
Changes requested	Blocked
PR merged	Done
PR closed without merging	REMOVE from board

⚠ Removal happens only when PRs close without merging to prevent clutter.

---

Basic Maintenance Guide

When to Update the Workflow

Update if:

• Status column names change
• New columns are added/removed
• Project number changes
• GitHub App permissions change

Maintenance Tasks

Task	Who Can Do It
Rotate App PEM Keys	Org Owner only
Add/remove workflow in repos	Maintainer or Owner
Update status labels	Instructor or Maintainer
Clean orphaned board items	Maintainer

Common Problems & Fixes

Problem	Cause	Fix
Missing STATUS_FIELD_ID	Board renamed	Update board or workflow
Token forbidden	App not installed org-wide	Reinstall
Removal fails	Item never added	Safe to ignore
GraphQL field missing	GitHub API changed	Rerun query & update

---

Links to the Actual Files

• Status Sync Workflow

• GitHub App Settings

---