diff --git a/.github/workflows/issue-classifier.lock.yml b/.github/workflows/issue-classifier.lock.yml index 254bbbc7020..0419610e59c 100644 --- a/.github/workflows/issue-classifier.lock.yml +++ b/.github/workflows/issue-classifier.lock.yml @@ -2242,7 +2242,7 @@ jobs: path: /tmp/gh-aw/aw_info.json if-no-files-found: warn - name: Run AI Inference - uses: actions/ai-inference@334892bb203895caaed82ec52d23c1ed9385151e # v1 + uses: actions/ai-inference@334892bb203895caaed82ec52d23c1ed9385151e # v2.0.4 env: GH_AW_MCP_CONFIG: /tmp/gh-aw/mcp-config/mcp-servers.json GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt diff --git a/.github/workflows/release.lock.yml b/.github/workflows/release.lock.yml index 8433f151f17..ce61da11ec3 100644 --- a/.github/workflows/release.lock.yml +++ b/.github/workflows/release.lock.yml @@ -6056,13 +6056,13 @@ jobs: - name: Download Go modules run: go mod download - name: Generate SBOM (SPDX format) - uses: anchore/sbom-action@43a17d6e7add2b5535efe4dcae9952337c479a93 # v0.20.10 + uses: anchore/sbom-action@43a17d6e7add2b5535efe4dcae9952337c479a93 # v0.20.11 with: artifact-name: sbom.spdx.json format: spdx-json output-file: sbom.spdx.json - name: Generate SBOM (CycloneDX format) - uses: anchore/sbom-action@43a17d6e7add2b5535efe4dcae9952337c479a93 # v0.20.10 + uses: anchore/sbom-action@43a17d6e7add2b5535efe4dcae9952337c479a93 # v0.20.11 with: artifact-name: sbom.cdx.json format: cyclonedx-json @@ -6261,7 +6261,7 @@ jobs: fetch-depth: 0 persist-credentials: false - name: Release with gh-extension-precompile - uses: cli/gh-extension-precompile@9e2237c30f869ad3bcaed6a4be2cd43564dd421b # v2 + uses: cli/gh-extension-precompile@9e2237c30f869ad3bcaed6a4be2cd43564dd421b # v2.1.0 with: build_script_override: scripts/build-release.sh go_version_file: go.mod diff --git a/.github/workflows/stale-repo-identifier.lock.yml b/.github/workflows/stale-repo-identifier.lock.yml index a8cd91dcd02..21caadf4297 100644 --- a/.github/workflows/stale-repo-identifier.lock.yml +++ b/.github/workflows/stale-repo-identifier.lock.yml @@ -176,7 +176,7 @@ jobs: ORGANIZATION: ${{ env.ORGANIZATION }} id: stale-repos name: Run stale_repos tool - uses: github/stale-repos@a21e55567b83cf3c3f3f9085d3038dc6cee02598 # v3 + uses: github/stale-repos@a21e55567b83cf3c3f3f9085d3038dc6cee02598 # v3.0.2 - env: INACTIVE_REPOS: ${{ steps.stale-repos.outputs.inactiveRepos }} name: Save stale repos output diff --git a/.github/workflows/super-linter.lock.yml b/.github/workflows/super-linter.lock.yml index b15660af2fb..4c2fde522cd 100644 --- a/.github/workflows/super-linter.lock.yml +++ b/.github/workflows/super-linter.lock.yml @@ -6189,7 +6189,7 @@ jobs: persist-credentials: false - name: Super-linter id: super-linter - uses: super-linter/super-linter@47984f49b4e87383eed97890fe2dca6063bbd9c3 # v8.2.1 + uses: super-linter/super-linter@47984f49b4e87383eed97890fe2dca6063bbd9c3 # v8.3.1 env: CREATE_LOG_FILE: "true" DEFAULT_BRANCH: main diff --git a/docs/src/content/docs/examples/issue-pr-events/projectops.md b/docs/src/content/docs/examples/issue-pr-events/projectops.md index e0f9b15d65e..66fe5eb7c9e 100644 --- a/docs/src/content/docs/examples/issue-pr-events/projectops.md +++ b/docs/src/content/docs/examples/issue-pr-events/projectops.md @@ -15,34 +15,24 @@ Then the [`update-project`](/gh-aw/reference/safe-outputs/#project-board-updates 1. **Create a Project**: Before you wire up a workflow, you must first create the Project in the GitHub UI (user or organization level). Keep the Project URL handy (you'll need to reference it in your workflow instructions). -2. **Create a token**: The kind of token you need depends on whether the Project you created is **user-owned** or **organization-owned** -For user-owned projects, use a **classic PAT** with `read:project` scope (for queries) or `project` scope (for queries and mutations). +2. **Create a token**: The kind of token you need depends on whether the Project you created is **user-owned** or **organization-owned**. -Required scopes: +#### User-owned Projects (v2) +Use a **classic PAT** with scopes: - `project` (required for user Projects) - `repo` (required if accessing private repositories) -Create at: [https://github.com/settings/tokens/new](https://github.com/settings/tokens/new) - #### Organization-owned Projects (v2) -You can use either a classic or fine-grained PAT. - -**Classic PAT** scopes: - -- `project` (required) -- `read:org` (required for org Projects) -- `repo` (required if accessing private repositories) - -**Fine-grained PAT** settings: - -- Repository access: Select specific repos or "All repositories" -- Organization access: Must be granted to the target organization -- Organization permissions: Projects = Read+Write -- Important: Fine-grained PATs work by default only for public org resources. You must explicitly grant organization access and Projects permissions. - -Create at: [https://github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new) +Use a **fine-grained** PAT with scopes: +- Repository access: Select specific repos that will use the workflow +- Repository permissions: + - Contents: Read + - Issues: Read (if workflow is triggered by issues) + - Pull requests: Read (if workflow is triggered by pull requests) +- Organization permissions: + - Projects: Read & Write (required for updating projects) ### 3) Store the token as a secret @@ -74,6 +64,10 @@ on: permissions: contents: read actions: read +tools: + github: + toolsets: [default, projects] + github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} safe-outputs: update-project: max: 1 @@ -103,8 +97,8 @@ ProjectOps workflows use the `update-project` safe output to ensure secure proje ```yaml wrap safe-outputs: update-project: - max: 10 # Optional: max project operations (default: 10) - github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} # Required: PAT with Projects access (default GITHUB_TOKEN won't work) + max: 10 + github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} ``` The `update-project` tool provides intelligent project management: @@ -115,95 +109,47 @@ The `update-project` tool provides intelligent project management: - **Applies a tracking label**: When adding a new item, it can apply a consistent tracking label to the underlying issue/PR - **Returns outputs**: Exposes the Project item ID (`item-id`) for downstream steps -## Accessing Issue Context +## Organization-Owned Project Configuration -ProjectOps workflows can access sanitized issue content through the `needs.activation.outputs.text` variable, which combines the issue title and description while removing security risks: +For workflows that interact with organization-owned projects and need to query GitHub information, use the following configuration: ```yaml wrap -# In your workflow instructions: -Analyze this issue to determine priority: "${{ needs.activation.outputs.text }}" -``` - -**Security Note**: Always treat user content as potentially untrusted and design workflows to be resilient against prompt injection attempts. - -## Common ProjectOps Patterns - -### Initiative Launch and Tracking - -Use an existing project board for a focused initiative and add related issues with tracking metadata. - -Create the initiative Project in the GitHub UI first (the `update-project` safe output does not create Projects). - -This goes beyond native GitHub automation by analyzing the codebase to generate related issues and coordinating multiple related work items. - -```aw wrap --- on: - workflow_dispatch: - inputs: - initiative_name: - description: "Initiative name" - required: true + issues: + types: [opened] permissions: contents: read actions: read +tools: + github: + toolsets: [default, projects] + github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} safe-outputs: - create-issue: - max: 20 update-project: - max: 20 + github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} --- -# Launch Initiative - -Use the initiative project board: "{{inputs.initiative_name}}" - -Analyze the repository to identify tasks needed for this initiative. +# Smart Issue Triage for Organization Project -For each task: -1. Create an issue with detailed description -2. Add the issue to the initiative project board -3. Set status to "Todo" -4. Set priority based on impact -5. Apply a tracking label for reporting - -The initiative board provides a visual dashboard showing all related work. +Analyze the issue and add it to the organization project board... ``` +This configuration ensures: +1. The GitHub MCP toolset can query repository and project information +2. The `update-project` safe output can modify the organization project +3. Both operations use the same token with appropriate permissions +## Accessing Issue Context -### Content-Based Priority Assignment - -Analyze issue content to set priority automatically, going beyond what labels can provide: - -```aw wrap ---- -on: - issues: - types: [opened] -permissions: - contents: read - actions: read -safe-outputs: - update-project: - max: 1 ---- - -# Intelligent Priority Triage - -When an issue is created, analyze its content to set priority and effort. - -Analyze the issue description for: -- Security vulnerabilities → Priority: "Critical", add to "Security" project -- Production crashes or data loss → Priority: "High", Effort: "Medium" -- Performance degradation → Priority: "High", Effort: "Large" -- Minor bugs or improvements → Priority: "Low", Effort: "Small" +ProjectOps workflows can access sanitized issue content through the `needs.activation.outputs.text` variable, which combines the issue title and description while removing security risks: -Add to "Engineering Backlog" project with calculated priority and effort fields. +```yaml wrap +# In your workflow instructions: +Analyze this issue to determine priority: "${{ needs.activation.outputs.text }}" ``` -**Why use ProjectOps:** Native GitHub automation can't analyze issue content to determine priority - it only reacts to labels and status changes. - +**Security Note**: Always treat user content as potentially untrusted and design workflows to be resilient against prompt injection attempts. ## Project Management Features diff --git a/docs/src/content/docs/reference/tokens.md b/docs/src/content/docs/reference/tokens.md index 721eff47cdb..20c076dfd11 100644 --- a/docs/src/content/docs/reference/tokens.md +++ b/docs/src/content/docs/reference/tokens.md @@ -216,12 +216,15 @@ You can use either a classic PAT or a fine-grained PAT: - `read:org` (required for org Projects) - `repo` (required if accessing private repositories) -2. **Option B**: Create a [fine-grained PAT](https://github.com/settings/personal-access-tokens/new) with: - - Repository access: Select specific repos or "All repositories" +2. **Option B (recommended)**: Create a [fine-grained PAT](https://github.com/settings/personal-access-tokens/new) 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): - - **Organization access**: Must be granted to the target organization - - **Projects**: Read+Write (for creating and managing org Projects) - - **Important**: Fine-grained PATs work by default only for public org resources. You must explicitly grant organization access and Projects permissions. + - Projects: Read & Write (required for updating org Projects) + - **Important**: You must explicitly grant organization access during token creation 3. **Option C**: Use a GitHub App with Projects: Read+Write permission @@ -252,8 +255,19 @@ The compiler automatically sets the `GH_AW_PROJECT_GITHUB_TOKEN` environment var safe-outputs: update-project: github-token: ${{ secrets.CUSTOM_PROJECT_TOKEN }} + +# Option 3: Organization projects with GitHub tools integration +tools: + github: + toolsets: [default, projects] + github-token: ${{ secrets.ORG_PROJECT_WRITE }} +safe-outputs: + update-project: + github-token: ${{ secrets.ORG_PROJECT_WRITE }} ``` +**For organization-owned projects**, the complete configuration should include both the GitHub tools and safe outputs using the same token with appropriate permissions. + :::note[Default behavior] By default, `update-project` is **update-only**: it will not create projects. If a project doesn't exist, the job fails with instructions to create it manually. @@ -261,7 +275,11 @@ By default, `update-project` is **update-only**: it will not create projects. If **GitHub Projects v2 PAT Requirements**: - **User-owned Projects**: Require a **classic PAT** with the `project` scope (plus `repo` if accessing private repos). Fine-grained PATs do **not** work with user-owned Projects. -- **Organization-owned Projects**: Can use either a classic PAT with `project` + `read:org` scopes, **or** a fine-grained PAT with explicit Organization access granted plus Projects: Read+Write permission. Fine-grained PATs work by default only for public org resources and must be explicitly granted organization access. +- **Organization-owned Projects**: Can use either a classic PAT with `project` + `read:org` scopes, **or** a fine-grained PAT with: + - Repository access to specific repositories + - Repository permissions: Contents: Read, Issues: Read, Pull requests: Read (as needed) + - Organization permissions: Projects: Read & Write + - Explicit organization access granted during token creation - **GitHub App**: Works for both user and org Projects with Projects: Read+Write permission. To opt-in to creating projects, the agent must include `create_if_missing: true` in its output, and the token must have sufficient permissions to create projects in the organization.