Problem

Following the Project Board Maintainer pattern with github-app instead of PATs, update-project fails with NOT_FOUND on items that reference issues.

The handler appears to resolve issue-backed project items via repository.issue(number:), which requires issues: read, but the safe-outputs GitHub App token minted for update-project does not currently include that permission.

Expected behavior

safe-outputs.update-project should work with github-app tokens for issue-backed project items when the GitHub App installation has the required permissions configured.

Analysis

This looks like a permission computation gap during workflow generation rather than a runtime GitHub App configuration problem.

Relevant implementation points:

• pkg/workflow/safe_outputs_permissions.go currently gives update-project NewPermissionsContentsReadProjectsWrite().
• pkg/workflow/permissions_factory.go shows that helper adds:
  • contents: read
  • organization-projects: write
• It does not add issues: read.
• pkg/workflow/safe_outputs_app_config.go already forwards PermissionIssues to permission-issues, so the missing piece appears to be permission accumulation for update-project, not app-token field conversion.

This also matches the observed workaround: manually adding permission-issues: read to the GitHub App token mint step in the compiled lock file makes the workflow succeed.

Repro

github-app:
  app-id: ${{ vars.APP_ID }}
  private-key: ${{ secrets.APP_PRIVATE_KEY }}
  owner: my-org

safe-outputs:
  update-project:
    project: https://github.com/orgs/my-org/projects/1

The GitHub App has these permissions configured:

• Issues: Read
• Organization projects: Read and write

Workaround

Manually adding permission-issues: read to the GitHub App token mint step in the compiled lock file works around the issue.

Proposed implementation plan

1. Update the safe-output permission computation for update-project in pkg/workflow/safe_outputs_permissions.go so issue-backed project item resolution receives issues: read in addition to the existing project permissions.
2. Keep the scope narrow. Prefer fixing only the update-project permission set rather than broadening unrelated safe outputs.
3. If needed for clarity, introduce a dedicated helper in pkg/workflow/permissions_factory.go for the exact permission combination instead of overloading a helper used by other project-related operations.
4. Add a regression test around GitHub App token generation, likely in pkg/workflow/safe_outputs_app_test.go or an adjacent workflow test, asserting that update-project with github-app emits permission-issues: read in the generated safe-outputs job.
5. Add or update any focused permission/spec tests so the intended permission combination is documented in tests as well.
6. Update documentation where appropriate, for example docs/src/content/docs/reference/tokens.md or the safe-outputs reference, to clarify that issue-backed update-project operations require issue-read access on the minted token.
7. Run make agent-finish before considering the fix complete.

Acceptance criteria

• Generated workflow includes permission-issues: read for the relevant update-project GitHub App token mint step.
• update-project succeeds for issue-backed project items when the App installation has the expected permissions.
• Regression tests cover the missing permission so this does not recur.