diff --git a/docs/public/images/projectops-write-board_dark.png b/docs/public/images/projectops-write-board_dark.png new file mode 100644 index 00000000000..95ce9995d6c Binary files /dev/null and b/docs/public/images/projectops-write-board_dark.png differ diff --git a/docs/public/images/projectops-write-board_light.png b/docs/public/images/projectops-write-board_light.png new file mode 100644 index 00000000000..f62da3478ac Binary files /dev/null and b/docs/public/images/projectops-write-board_light.png differ diff --git a/docs/public/images/projectops-write-issue_dark.png b/docs/public/images/projectops-write-issue_dark.png new file mode 100644 index 00000000000..8493afdf63e Binary files /dev/null and b/docs/public/images/projectops-write-issue_dark.png differ diff --git a/docs/public/images/projectops-write-issue_light.png b/docs/public/images/projectops-write-issue_light.png new file mode 100644 index 00000000000..6c22bc7967a Binary files /dev/null and b/docs/public/images/projectops-write-issue_light.png differ diff --git a/docs/src/content/docs/examples/project-tracking.md b/docs/src/content/docs/examples/project-tracking.md index 5d2c88f2ce1..e36ea52e952 100644 --- a/docs/src/content/docs/examples/project-tracking.md +++ b/docs/src/content/docs/examples/project-tracking.md @@ -75,7 +75,7 @@ See [Safe Outputs: Project Board Updates](/gh-aw/reference/safe-outputs/#project ### Authentication -See [Authentication (Projects)](/gh-aw/reference/auth-projects/). +See [Project token authentication](/gh-aw/patterns/project-ops/#project-token-authentication). ## Example: Issue Triage @@ -283,6 +283,6 @@ Update the project item with the team field. - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Complete safe-outputs documentation - [update-project](/gh-aw/reference/safe-outputs/#project-board-updates-update-project) - Detailed update-project configuration - [create-project-status-update](/gh-aw/reference/safe-outputs/#project-status-updates-create-project-status-update) - Status update configuration -- [GitHub Projects Authentication](/gh-aw/reference/auth-projects/) - Token setup guide +- [Project token authentication](/gh-aw/patterns/project-ops/#project-token-authentication) - Token setup guide - [Projects & Monitoring](/gh-aw/patterns/monitoring/) - Design pattern guide - [Orchestration](/gh-aw/patterns/orchestration/) - Design pattern guide diff --git a/docs/src/content/docs/patterns/project-ops.mdx b/docs/src/content/docs/patterns/project-ops.mdx index 0e6adea02bb..11b8d21a7c8 100644 --- a/docs/src/content/docs/patterns/project-ops.mdx +++ b/docs/src/content/docs/patterns/project-ops.mdx @@ -9,16 +9,54 @@ ProjectOps helps teams run project operations with less manual upkeep. It builds on [GitHub Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-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](/gh-aw/reference/safe-outputs/). -ProjectOps is most useful when you want context-aware routing and field updates; for simple, rule-based transitions, [built-in automations](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations) are usually enough. +ProjectOps reads project state with GitHub tools and applies changes through [safe-outputs](/gh-aw/reference/safe-outputs/). +It is most useful when you need context-aware routing and field updates. For simple, rule-based transitions, [built-in automations](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-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`](/gh-aw/reference/auth-projects/). -3. **Define your field contract** up front (for example: Status, Priority, Team, Iteration, Target Date). See [Understanding fields](https://docs.github.com/en/issues/planning-and-tracking-with-projects/understanding-fields). +1. **A Project board** and copy the project URL. See [Creating a project](https://docs.github.com/en/issues/planning-and-tracking-with-projects/creating-projects/creating-a-project#creating-a-project). +2. **A Project token** (PAT or GitHub App token). See [Authentication for Project Operations](#authentication-for-project-operations). +3. **A field contract** (for example: Status, Priority, Team, Iteration, Target Date). See [Understanding fields](https://docs.github.com/en/issues/planning-and-tracking-with-projects/understanding-fields). + +## Authentication for Project Operations + +Project operations need additional authentication because the default `GITHUB_TOKEN` is repository-scoped and cannot access Projects APIs for read/write project operations. + +### User-owned Projects + +If your project is user-owned, use a PAT and store it as a repository secret. + +- Use a [classic PAT](https://github.com/settings/tokens/new). +- Required scopes: + - `project` + - `repo` (if private repositories are involved) + +### Organization-owned Projects + +If your project is organization-owned, use a fine-grained PAT or a GitHub App token and store it as a repository secret. + +- Use a [fine-grained PAT](https://github.com/settings/personal-access-tokens/new?name=GH_AW_WRITE_PROJECT_TOKEN&description=GitHub+Agentic+Workflows+-+Projects+authentication&contents=read&issues=read&pull_requests=read). +- Configure: + - Repository access: select the repositories that will run the workflow. + - Repository permissions: `Contents: Read`, and optionally `Issues: Read` / `Pull requests: Read`. + - Organization permissions: `Projects: Read and write`. + +You can also use a GitHub App token if your organization standardizes on App-based auth. +For organization projects, make sure the app has **Organization Projects: Read and write** permission. +See [Using a GitHub App for Authentication](/gh-aw/reference/auth/#using-a-github-app-for-authentication). + +### Recommended secret layout + +Use separate read and write tokens so you can enforce least privilege: +- `GH_AW_READ_PROJECT_TOKEN` for `tools.github` + `projects` toolset. +- `GH_AW_WRITE_PROJECT_TOKEN` for safe-output writes like `update-project`. + +```bash wrap +gh aw secrets set GH_AW_READ_PROJECT_TOKEN --value "" +gh aw secrets set GH_AW_WRITE_PROJECT_TOKEN --value "" +``` ## How it works @@ -34,16 +72,11 @@ ProjectOps combines two capability layers: Let's look at examples of these in action, starting with the [Project Board Summarizer](#project-board-summarizer) (read-only analysis), then moving to controlled write operations with the [Project Board Maintainer](#project-board-maintainer) example. -### Project Board Summarizer +## Examples -Start with a regular project review that summarizes changes, flags blockers, and suggests updates without applying changes. - -Our project board might look like this: +### Project Board Summarizer (Read-only) - - - Example GitHub Projects board used for Project Board Summarizer - +Let's start with a simple agentic workflow that reviews project board state and generates a summary without applying any changes. ```aw wrap --- @@ -55,8 +88,8 @@ permissions: actions: read tools: github: - toolsets: [default, projects] github-token: ${{ secrets.GH_AW_READ_PROJECT_TOKEN }} + toolsets: [default, projects] --- # Project Board Summarizer @@ -73,17 +106,23 @@ Return only: 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: +Our project board might look like this: + + + + Example GitHub Projects board used for Project Board Summarizer + + +Running the agentic workflow generates a concise summary of project status. We can find this in the GitHub Actions agent run output: Workflow summary output generated by Project Board Summarizer -### Project Board Maintainer +### Project Board Maintainer (Write) -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. +Let's write an agentic workflow that applies changes to a project board based on issue content and context. +This workflow will run on new issues, analyze the issue and project state, and decide whether to add the issue to the project board and how to set key fields. ```aw wrap --- @@ -95,29 +134,46 @@ permissions: actions: read tools: github: + github-token: ${{ secrets.GH_AW_READ_PROJECT_TOKEN }} toolsets: [default, projects] - github-token: ${{ secrets.READ_PROJECT_GITHUB_TOKEN }} safe-outputs: update-project: - project: https://github.com/orgs/ORG/projects/123456 + github-token: ${{ secrets.GH_AW_WRITE_PROJECT_TOKEN }} + project: https://github.com/orgs/my-mona-org/projects/1 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. +Analyze each new issue in this repository and decide whether it belongs on the project 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. +Post a short comment on the issue explaining your routing decision and any uncertainty. ``` +Once this workflow is compiled and running, it will automatically triage new issues with controlled write operations to the project board and issue comments. + +Let's create a new issue to see this in action: + + + + Workflow summary output generated by Project Board Maintainer + + +The Project Board Maintainer analyzes the issue content and context, then decides to add it to the project board with specific field values (for example, Status: Proposed, Priority: Medium, Team: Docs). +It also posts a comment on the issue explaining the decision and any uncertainty. + + + + Workflow summary output generated by Project Board Maintainer + + ## 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. @@ -129,4 +185,9 @@ In production, keep the loop simple: issue arrives, agent classifies and propose - Keep single-select values exact to avoid field drift. - If you only need simple event-based transitions, prefer [built-in GitHub Project workflows](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations). -References: [Authentication (Projects)](/gh-aw/reference/auth-projects/), [Safe Outputs Reference](/gh-aw/reference/safe-outputs/), [Projects & Monitoring](/gh-aw/patterns/monitoring/), and [IssueOps](/gh-aw/patterns/issue-ops/). +## Related documentation + +- **[Authentication for Project Operations](/gh-aw/patterns/project-ops/#authentication-for-project-operations)** +- **[Safe Outputs Reference](/gh-aw/reference/safe-outputs/)** +- **[Projects & Monitoring](/gh-aw/patterns/monitoring/)** +- **[IssueOps](/gh-aw/patterns/issue-ops/)** diff --git a/docs/src/content/docs/reference/auth-projects.mdx b/docs/src/content/docs/reference/auth-projects.mdx deleted file mode 100644 index 3a8e0682f18..00000000000 --- a/docs/src/content/docs/reference/auth-projects.mdx +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Authentication (Projects) -description: How to authenticate GitHub Projects operations in agentic workflows -sidebar: - order: 651 ---- - -import { Card, CardGrid } from '@astrojs/starlight/components'; -import Video from '../../../components/Video.astro'; - -Project operations require additional authentication since the default `GITHUB_TOKEN` lacks necessary permissions for the Projects API. You can authenticate using either a Personal Access Token (PAT) or a GitHub App token. - -## Using a Personal Access Token (PAT) - -1. Create the PAT - - **For User-owned Projects**: - - Create a [classic PAT](https://github.com/settings/tokens/new) with scopes: - - `project` (required for user Projects) - - `repo` (required if accessing private repositories) - - **For Organization-owned Projects (v2)**: - - Create a [fine-grained PAT](https://github.com/settings/personal-access-tokens/new?name=GH_AW_PROJECT_GITHUB_TOKEN&description=GitHub+Agentic+Workflows+-+Projects+authentication&contents=read&issues=read&pull_requests=read) (this link pre-fills the token name, description, and repository permissions) with: - - **Repository access**: Select specific repos that will use the workflow - - **Repository permissions**: - - Contents: Read - - Issues: Read (if needed for issue-triggered workflows) - - Pull requests: Read (if needed for PR-triggered workflows) - - **Organization permissions** (must be explicitly granted): - - Projects: Read & Write (required for updating org Projects) - - **Important**: You must explicitly grant organization access during token creation - -2. Add the token to repository secrets - - ```bash wrap - gh aw secrets set MY_PROJECT_TOKEN --value "YOUR_PROJECT_PAT" - ``` - -3. Configure in your workflow frontmatter - - ```yaml wrap - safe-outputs: - update-project: - github-token: ${{ secrets.MY_PROJECT_TOKEN }} - - tools: - github: - toolsets: [default, projects] - github-token: ${{ secrets.MY_PROJECT_TOKEN }} - ``` - -## Using a GitHub App - -Alternatively, you can use a GitHub App for enhanced security. See [Using a GitHub App for Authentication](/gh-aw/reference/auth/#using-a-github-app-for-authentication) for complete setup instructions. Once set up, reference the app token in your workflow using `app:` on safe outputs and tools. - -## Using a magic secret - -Alternatively, you can set the magic GitHub Actions secret `GH_AW_PROJECT_GITHUB_TOKEN` to a suitable PAT (see the above guide for creating a suitable PAT). This secret name is known to GitHub Agentic Workflows and does not need to be explicitly referenced in your workflow. - -```bash wrap -gh aw secrets set GH_AW_PROJECT_GITHUB_TOKEN --value "" -``` - -