fix(issue-auto-implement): remove invalid workflows permission, document repo setting (#260)

* docs(issue-auto-implement): document CI trigger and approval for bot-created PRs

Made-with: Cursor

* fix(issue-auto-implement): add workflows: write so push succeeds when implement changes workflow files

Made-with: Cursor

* docs(issue-auto-implement): document workflows: write when implement may edit workflow files

Made-with: Cursor

* fix(issue-auto-implement): remove invalid workflows permission, document repo setting

workflows is not a valid key in workflow permissions syntax; it caused
'Unexpected value workflows' and broke the workflow run. Document that
workflow file pushes may require repo Settings → Actions → Allow
GitHub Actions to create and approve pull requests, or a PAT.

Made-with: Cursor

Author: leggetter

.github/actions/issue-auto-implement/README.md

@@ -4,7 +4,7 @@ Reusable composite action for label-triggered issue automation: assess (request
 
 ## How to use (quick start)
 
-1. **Workflow** — Ensure `.github/workflows/issue-auto-implement.yml` exists and calls this action (see the workflow in this repo for the exact `on:` and `uses:`). If implement might change workflow files, the job must include `workflows: write` in its `permissions` (see [CI/CD](#cicd-what-you-need-to-run-this-workflow)).
+1. **Workflow** — Ensure `.github/workflows/issue-auto-implement.yml` exists and calls this action (see the workflow in this repo for the exact `on:` and `uses:`). If implement might change workflow files, see [CI/CD](#cicd-what-you-need-to-run-this-workflow) for push permission requirements.
 2. **Secrets and variables** — In the repo: Settings → Secrets and variables → Actions. Add secret **`AUTO_IMPLEMENT_ANTHROPIC_API_KEY`** (Anthropic API key). For who can trigger, set **one** of: **`AUTO_IMPLEMENT_ALLOWED_TRIGGER_MIN_PERMISSION`** (e.g. `push` or `maintain`; works with default token) or **`AUTO_IMPLEMENT_ALLOWED_TRIGGER_TEAM`** (e.g. `org/team`; token needs `read:org`).
 3. **Trigger label** — Create the labels once so you can add them to issues. Either run the **Issue auto-implement setup** workflow (Actions → Issue auto-implement setup → Run workflow), which creates `automation/auto-implement`, `automation/needs-info`, and `automation/pr-created`; or create the trigger label **`automation/auto-implement`** manually in the repo (Settings or Issues → Labels). The main action also ensures these labels exist when it runs, but the trigger label must exist before you can add it to an issue.
 4. **Trigger** — On an issue, add the label `automation/auto-implement`. The workflow runs: it assesses the issue (request more info vs implement), and if implement, runs the Claude Code CLI and opens a PR. You can also comment on the issue (to add context and re-trigger) or review the PR (to iterate).
@@ -15,6 +15,10 @@ PRs created by the action use `GITHUB_TOKEN`, so GitHub does not trigger `pull_r
 
 To require a human to approve workflow runs before they execute (e.g. for security), set **Settings → Actions → General → Approval for running fork pull request workflows from contributors** to **Require approval for all external contributors**. Then each bot-created PR will show workflow(s) awaiting approval until someone with write access approves.
 
+## Extra workflow runs when the action adds labels
+
+The workflow is triggered by `issues.labeled`. When this action adds a label (e.g. `automation/needs-info` or `automation/pr-created`), GitHub sends a new `issues.labeled` event, so **another workflow run is started**. The job only runs when the label added is **`automation/auto-implement`** (see the workflow’s `if:`), so those extra runs **skip the job** and do no work. You will see multiple runs per issue; only the runs triggered by the trigger label (or by comment/PR review) actually execute the action. GitHub does not support filtering `on: issues.labeled` by label name, so this behavior is expected.
+
 ## Usage (reference)
 
 Used by `.github/workflows/issue-auto-implement.yml`. Requires `anthropic_api_key` (e.g. from repo secret `AUTO_IMPLEMENT_ANTHROPIC_API_KEY`), one of `github_allowed_trigger_min_permission` or `github_allowed_trigger_team` (repo variables), and `github_token` from the workflow.
@@ -42,7 +46,7 @@ Secrets and variables use an action-specific prefix (e.g. `AUTO_IMPLEMENT_`) so
 
 To use this action in GitHub Actions:
 
-1. **Workflow** — Call the action from a workflow (e.g. `.github/workflows/issue-auto-implement.yml`) on `issues.labeled`, `issue_comment`, `pull_request_review`, and/or `pull_request_review_comment`. The job needs `contents: write`, `issues: write`, `pull-requests: write`. If the implement step may edit files under `.github/workflows/`, also add **`workflows: write`** so the push is allowed (GitHub rejects workflow file changes without it).
+1. **Workflow** — Call the action from a workflow (e.g. `.github/workflows/issue-auto-implement.yml`) on `issues.labeled`, `issue_comment`, `pull_request_review`, and/or `pull_request_review_comment`. The job needs `contents: write`, `issues: write`, `pull-requests: write`. If the implement step may edit files under `.github/workflows/`, GitHub may reject the push; the workflow syntax has no `workflows` permission key. Enable **Settings → Actions → General → Allow GitHub Actions to create and approve pull requests** (or use a PAT with appropriate scope) so the run can push workflow file changes.
 2. **Secrets** — Add **`AUTO_IMPLEMENT_ANTHROPIC_API_KEY`** (repo secret). Used for the assess step and passed to the Claude Code CLI in the implement step.
 3. **Variables (trigger gate)** — Set **one** of:
    - **`AUTO_IMPLEMENT_ALLOWED_TRIGGER_MIN_PERMISSION`** (repo variable): `triage`, `push`, `maintain`, or `admin`. Only users with at least this repo permission can trigger. Works with default `GITHUB_TOKEN`.

.github/workflows/issue-auto-implement.yml

@@ -13,7 +13,7 @@ on:
   pull_request_review_comment:
     types: [created]
 
-# Only run for the trigger label on issues (action will further filter issue_comment and PR events)
+# Only run the job when the trigger label was added (not when our action adds needs-info/pr-created; those trigger a run but this if skips the job)
 jobs:
   run:
     runs-on: ubuntu-latest
@@ -27,7 +27,8 @@ jobs:
       issues: write
       pull-requests: write
       actions: write  # trigger test workflow on PR branch so checks appear (PRs created by bot may not trigger pull_request)
-      workflows: write  # allow push when implement touches .github/workflows/* (GitHub rejects workflow file changes without this)
+      # To allow push when implement touches .github/workflows/*: repo Settings → Actions → General →
+      # "Allow GitHub Actions to create and approve pull requests" (or use a PAT with workflow scope). No workflows: key in workflow syntax.
       # read:org only needed if using team check (AUTO_IMPLEMENT_ALLOWED_TRIGGER_TEAM)
     steps:
       - name: Checkout