ProjectOps

ProjectOps helps teams run project operations with less manual upkeep.

It builds on GitHub Projects, which provides the core planning and tracking layer for issues and pull requests, and adds support for judgment-heavy decisions.

It uses a clear control model: the agent reads project state through GitHub tools (tools.github with the projects toolset), and write actions run through safe-outputs. ProjectOps is most useful when you want context-aware routing and field updates; for simple, rule-based transitions, built-in automations are usually enough.

In practice, this gives teams faster triage decisions, cleaner board state, stronger planning signals across related issues and pull requests, and more decision-ready status updates.

Prerequisites

1. Create a Projects board and copy the project URL.
2. Create PAT by following instructions for GH_AW_PROJECT_GITHUB_TOKEN.
3. Define your field contract up front (for example: Status, Priority, Team, Iteration, Target Date). See Understanding fields.

How it works

A practical way to adopt ProjectOps is to start with read-only MCP/GitHub analysis, then gradually add targeted write operations as workflow confidence and policy maturity increase.

ProjectOps combines two capability layers:

• GitHub tools (tools.github + projects toolset) for reading and analyzing project state.
• Safe outputs for controlled write operations, including:
  • update-project — use when you want to add issues/PRs to a project or update fields (status, priority, owner, dates, custom values).
  • create-project-status-update — use when you want a stakeholder-facing summary in the project Updates tab (weekly health, blockers, risks, next decisions).
  • create-project — use when automation needs to bootstrap a new board for an initiative or team.
  • add-comment — use when you want to explain routing decisions or request missing info on the triggering issue/PR.

Let’s look at examples of these in action, starting with the Project Board Summarizer (read-only analysis), then moving to controlled write operations with the Project Board Maintainer example.

Project Board Summarizer

Start with a regular project review that summarizes changes, flags blockers, and suggests updates without applying changes.

Our project board might look like this:

---
on:
  schedule:
    - cron: "0 14 * * 1"
permissions:
  contents: read
  actions: read
tools:
  github:
    toolsets: [default, projects]
    github-token: ${{ secrets.GH_AW_READ_PROJECT_TOKEN }}
---

# Project Board Summarizer

Review [project 1](https://github.com/orgs/my-mona-org/projects/1).

Return only:

- New this week
- Blocked + why
- Stale/inconsistent fields
- Top 3 human actions

Read-only. Do not update the project.

Running this workflow generates a concise summary of project status. We can find this in the GitHub Actions agent run output:

Project Board Maintainer

Let’s write an agentic workflow that applies changes to a project board, starting with issue triage.

This workflow runs on new issues, analyzes issue content and context, and decides whether to add the issue to the project board and how to set key fields.

---
on:
  issues:
    types: [opened]
permissions:
  contents: read
  actions: read
tools:
  github:
    toolsets: [default, projects]
    github-token: ${{ secrets.READ_PROJECT_GITHUB_TOKEN }}
safe-outputs:
  update-project:
    project: https://github.com/orgs/ORG/projects/123456
    max: 1
    github-token: ${{ secrets.WRITE_PROJECT_GITHUB_TOKEN }}
  add-comment:
    max: 1
---

# Intelligent Issue Triage

Analyze each new issue and decide whether it belongs on the portfolio board.

Set structured fields only from allowed values:
- Status: Needs Triage | Proposed | In Progress | Blocked
- Priority: Low | Medium | High
- Team: Platform | Docs | Product

Post a short comment explaining your routing decision and any uncertainty.

Best practices

In production, keep the loop simple: issue arrives, agent classifies and proposes/sets fields, safe outputs apply allowed writes, and humans review high-impact changes and exceptions.

• Auto-apply low-risk hygiene (add item, set initial status/team).
• Suggest-only commitments (priority/date/iteration changes).
• Always gate cross-team or cross-repo impact.
• Use max caps, allowlists, and explicit approvals to control writes.
• Keep single-select values exact to avoid field drift.
• If you only need simple event-based transitions, prefer built-in GitHub Project workflows.

References: Authentication (Projects), Safe Outputs Reference, Projects & Monitoring, and IssueOps.