[Maintenance] Fix OC agent trigger reliability and response failures

[RussellSB]

Problem

The OpenCode (OC) agent in GitHub Actions sometimes fails to respond to /oc comments entirely, and sometimes enters loops when asked to create issues. This was observed consistently in PR #224.

Symptoms:

• Some /oc commands produce no response at all (no eyes emoji, no workflow run)
• Quote-reply comments with /oc after > blocks appear to not trigger the workflow
• When triggered, the agent sometimes asks for confirmation instead of acting on explicit instructions
• Git auth failures on the runner (Author identity unknown, could not read Username) suggest permission/scope issues

Observed in PR #224

Comment	Result
/oc address coderabitai's recent unresolved comments and resolve	Ran but failed — Author identity unknown (no git config)
/oc try again (quote-reply)	Ran but failed — fatal: could not read Username for 'https://github.com'
/oc in your latest commit you didnt follow git conventions...	Ran and responded with investigation/plan
/oc make an issue with your ideas so far, we will continue planning there	Ran but asked for confirmation instead of creating the issue
/oc why didnt my previous latest comment mentioning you trigger a run from you?	Ran and explained it did trigger, responded with analysis instead of action
/oc maybe it ran so quick i didnt see the eyes emoji...	Ran but still didn't create the issue

Key failure case: The user's initial quote-reply commands (steps 1–2) produced no visible trigger, leading to confusion about whether OC was working at all.

Likely Root Causes

1. Workflow trigger doesn't handle quote-reply formatting

The current condition:

contains(github.event.comment.body, ' /oc') || startsWith(github.event.comment.body, '/oc')

Fails for comments where /oc appears after markdown quote blocks (>), since the body starts with > not /oc, and /oc may not match depending on whitespace in the quoted text.

2. Insufficient runner permissions

Only id-token: write is granted. Git operations (push, commit) require contents: write and authenticated credentials (GITHUB_TOKEN or a PAT). The Author identity unknown and Username prompt errors confirm this.

3. Agent behaviour — confirmation loop

When asked to create an issue, the agent asked for confirmation instead of executing immediately, suggesting the system prompt or tool configuration may not be tuned for autonomous action on explicit user instructions.

Proposed Solution

1. Fix the trigger regex — Account for quote-reply blocks, leading whitespace, and inline /oc commands anywhere in the comment body
2. Grant necessary permissions — Add contents: write to the workflow permissions and ensure GITHUB_TOKEN is passed and git identity is configured on the runner
3. Tune agent autonomy — Adjust the system prompt so that explicit /oc commands like "make an issue" execute immediately without confirmation loops

Commit type note

This is a CI/tooling improvement. Commits for this issue must use chore: or ci: prefix — not fix: or feat: — to avoid triggering an auto-release via semantic-release on main. The conventionalcommits preset maps fix: → patch bump and feat: → minor bump; only chore:/ci:/docs:/refactor: produce no version bump.

Acceptance Criteria

• /oc commands inside quote-reply blocks (> /oc ...) trigger the workflow
• Agent can commit/push without auth failures
• Agent executes explicit instructions (e.g., "create an issue") without asking for confirmation
• No false negatives on any valid /oc command format

[coderabbitai]

🔗 Related PRs

#165 - ci(whats-new): migrate docs generator from GitHub Models to OpenCode Kimi K2.7-code [merged]
#173 - ci: add opencode access github app [merged]
#174 - ci(whats-new): switch model to deepseek-flash-v4 and increase timeout to 5min [merged]
#207 - ci: update opencode job conditions and permissions [merged]
#209 - ci: grant contents write permission to OpenCode agent [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Diagnose first: confirm from the actual opencode.yml run logs whether the loop is an App-token scope gap or an unscoped GITHUB_TOKEN, and bank that knowledge as reusable cicd skill guidance.
• Grant write access at both layers that matter — widen the workflow permissions: block for our own reaction step, and align the OpenCode App installation scopes for OC's own issue/PR writes.
• Replace the fragile substring trigger with a line-aware parse that survives quote-reply comments, and fire an explicit 👀 reaction the moment a command is detected.
• Cap the job with a timeout and instruct the agent to fail loudly on write errors so the create/retry loop can't recur.

Design Choices

Design Choice 1: Which authentication/permission path grants OC the ability to create issues and PRs?

Options Considered:

1. Keep OpenCode GitHub App auth and ensure the App installation is granted Contents/Issues/Pull requests write on the repo (configured in GitHub App settings, outside the repo).
2. Set use_github_token: true and grant the runner GITHUB_TOKEN the write scopes via the workflow permissions: block.
3. Use a dedicated PAT (mirroring DOCS_PREVIEW_PAT in whats-new.yaml).

Chosen Option: 1

Rationale: The loop is almost certainly a "permission denied → retry" cycle: opencode.yml grants no write scopes, and OC currently runs on the App installation token whose scopes aren't recorded anywhere in-repo. App auth was deliberately enabled and, unlike the GITHUB_TOKEN, App-authored PRs still trigger downstream CI (lint-pr-title, check-base-branch, test), which is exactly what OC-created PRs need; the in-repo permissions: block is still widened (see Phase 2) because our own acknowledgement step uses the runner GITHUB_TOKEN.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Diagnose the loop from the Action run logs

Before changing anything, confirm the actual failure mode from the real run the ticket references, and leave behind repeatable guidance so future OC-in-CI debugging isn't tribal knowledge. The working hypothesis — a write-permission failure driving a create/retry loop — must be verified against the logs, not assumed.

Task 1: Confirm the failure mode from the referenced run

Pin down whether the loop is a permission rejection, an auth-token scope gap, or an agent-side retry behaviour.

• Pull the failing run for the gradual-uptrend fix PR via gh run list --workflow=opencode.yml and gh run view <id> --log, and grep the OC step output for the issue/PR-creation call and its HTTP status (expect 403/404 on the create call if it's a scope problem).
• Distinguish the two candidate roots: (a) App-token missing Issues/Pull requests write, vs (b) runner GITHUB_TOKEN used but unscoped. Record which token OC actually used from the log lines.
• Capture the exact error string and the retry cadence so Phase 4's loop mitigation targets the real behaviour, not a guess.

Task 2: Add GitHub Actions log-debugging guidance to the cicd skill

There is currently no skill teaching an agent how to read its own CI run logs; this gap is why the ticket exists.

• Extend .opencode/skills/cicd/SKILL.md with a short "Debugging OpenCode Action runs" section covering gh run list/gh run view --log, filtering to the opencode job, and inspecting the create-issue/create-PR API responses.
• Note the auth model explicitly: OC runs on the App installation token (not GITHUB_TOKEN), so a 403 on write means the App installation scope, not the workflow permissions: block, is the lever.
• Keep it in cicd (not debug, which is scoped to the pytrendy pipeline) since that skill already owns .github/workflows/.

🤖 Prompt for AI agents

Diagnose the actual failure behind the OC create/retry loop by inspecting real
Action run logs, then bank that knowledge as skill guidance — do not change any
workflow behaviour in this phase.

- Pull the failing run for the gradual-uptrend fix PR using `gh run list
--workflow=opencode.yml` and `gh run view <id> --log`. Grep the OC step output
for the issue/PR-creation call and its HTTP status (expect `403`/`404` on the
create call if it's a scope problem).
- Distinguish two candidate roots: (a) the App-token is missing Issues/Pull
requests write, vs (b) the runner `GITHUB_TOKEN` is being used but unscoped.
Record from the log lines which token OC actually used.
- Capture the exact error string and the retry cadence — this evidence must
inform Phase 4's loop-guarding work.
- Extend `.opencode/skills/cicd/SKILL.md` with a new short section titled
something like "Debugging OpenCode Action runs", covering: using `gh run
list`/`gh run view --log`, filtering to the `opencode` job, and inspecting
create-issue/create-PR API responses.
- In that same section, state explicitly that OC runs on the App installation
token (not `GITHUB_TOKEN`), so a `403` on write points to the App installation
scope, not the workflow `permissions:` block.
- Place this guidance in the `cicd` skill (not `debug`, which is scoped to the
pytrendy pipeline), since `cicd` already owns `.github/workflows/`.

Phase 2: Grant OC the write access it needs

Give the agent — and our own acknowledgement step — the scopes required to react to comments and open issues/PRs. This is where the permission wall from Phase 1 gets torn down.

Task 1: Widen the workflow permission block

The current id-token: write-only block starves both OC and any first-party API call.

• Update .github/workflows/opencode.yml to add contents: write, issues: write, and pull-requests: write alongside the existing id-token: write.
• This is required regardless of the App-token outcome, because the 👀 reaction step in Phase 3 uses the runner GITHUB_TOKEN and needs issues/pull-requests write to POST a reaction.

Task 2: Verify and align the OpenCode App installation scopes

If OC writes via the App token, the workflow block alone won't fix issue/PR creation.

• Confirm (via GitHub App installation settings) that the OpenCode App is granted Contents, Issues, and Pull requests write on this repository; this is the fix if Task 1.1 shows the create call ran on the App token.
• Document the required App scopes in .opencode/skills/cicd/SKILL.md next to the secrets list so this isn't lost again — it's the one piece of config that lives outside the repo.
• Only if Task 1.1 proves OC cannot use the App token for writes, fall back to use_github_token: true in opencode.yml (now backed by the widened permissions); flag the trade-off that GITHUB_TOKEN-authored PRs won't trigger downstream CI.

🤖 Prompt for AI agents

Tear down the permission wall identified in Phase 1 by widening scopes at both
layers that matter: the workflow's own permission block and the OpenCode App
installation.

- In `.github/workflows/opencode.yml`, add `contents: write`, `issues: write`,
and `pull-requests: write` to the existing `permissions:` block alongside
`id-token: write`. This is required regardless of the App-token outcome, since
the Phase 3 acknowledgement step runs on the runner `GITHUB_TOKEN` and needs
`issues`/`pull-requests` write to POST a reaction.
- Separately, confirm via GitHub App installation settings that the OpenCode App
is granted Contents, Issues, and Pull requests write on this repository — this
is the actual fix if Phase 1's log check shows the create call ran on the App
token.
- Document the required App scopes in `.opencode/skills/cicd/SKILL.md`, next to
the existing secrets list, since this configuration lives outside the repo and
would otherwise be lost again.
- Only fall back to setting `use_github_token: true` in `opencode.yml` if Phase
1 proves OC cannot use the App token for writes. If applied, this relies on the
widened permissions block above, but flag the trade-off clearly:
`GITHUB_TOKEN`-authored PRs won't trigger downstream CI.

Phase 3: Harden comment-trigger detection and acknowledgement

Fix the silent-failure class where the job never runs — so no 👀 ever appears — because the brittle string check misses commands preceded by a quoted-reply block. Make detection robust, then make acknowledgement explicit and immediate rather than dependent on the third-party action.

Task 1: Replace the brittle string match with a proper parse step

The current startsWith(body,'/oc') || contains(body,' /oc') logic only inspects the very first character or space-prefixed occurrences; a quote-reply body starts with > and puts the command after a newline, so neither branch matches.

• In .github/workflows/opencode.yml, keep the cheap author_association gate at job level, but move command detection into a dedicated shell step that reads github.event.comment.body via env: (never string-interpolated into run:, to avoid injection).
• Parse line-by-line: strip Markdown quote lines (those starting with >), then match /oc or /opencode at a line start or on a word boundary; emit a should_run step output.
• This naturally handles quote-prefixed comments (the command sits on its own unquoted line) while still ignoring commands that appear only inside quoted text.

Task 2: Add an explicit 👀 acknowledgement before invoking OC

Don't rely on the third-party action to react — acknowledge as soon as a valid command is detected, which is exactly the behaviour the ticket says went missing.

• Add a step gated on should_run that POSTs an eyes reaction to the triggering comment via actions/github-script (using the runner GITHUB_TOKEN and the issues/pull-requests write scopes from Phase 2), branching on whether the event is an issue comment or a PR review comment.
• Gate the existing Run opencode step on the same should_run output so behaviour stays consistent between detection, acknowledgement, and execution.

🤖 Prompt for AI agents

Fix the silent-failure class where the trigger job never fires — meaning no 👀
ever appears — by replacing the brittle substring check with robust, line-aware
parsing, and by making acknowledgement explicit rather than dependent on the
third-party action.

- The current logic (`startsWith(body,'/oc') || contains(body,' /oc')`) only
checks the very first character or space-prefixed occurrences. A quote-reply
body starts with `>` and places the command after a newline, so neither branch
matches — this is the root of the silent failure.
- In `.github/workflows/opencode.yml`, keep the existing cheap
`author_association` gate at job level, but move command detection into a
dedicated shell step. Read `github.event.comment.body` via `env:` only — never
string-interpolate it directly into `run:`, to avoid injection.
- Parse the body line-by-line: strip Markdown quote lines (those starting with
`>`), then match `/oc` or `/opencode` at a line start or on a word boundary.
Emit a `should_run` step output from this step.
- This approach naturally handles quote-prefixed comments, since the actual
command sits on its own unquoted line, while still correctly ignoring commands
that appear only inside quoted text.
- Add a new step, gated on `should_run`, that POSTs an `eyes` reaction to the
triggering comment using `actions/github-script`. Use the runner `GITHUB_TOKEN`
and the `issues`/`pull-requests` write scopes granted in Phase 2, and branch the
logic depending on whether the event is an issue comment or a PR review comment.
- Gate the existing `Run opencode` step on the same `should_run` output, so
detection, acknowledgement, and execution all stay consistent with one another.

Phase 4: Guard against the create/retry loop

Ensure that if a write ever fails again, the run fails fast and visibly instead of spinning.

Bound the OC step and surface failures

A permission failure should be a clean, diagnosable stop — not a loop.

• Add a timeout-minutes to the opencode job in .github/workflows/opencode.yml so a looping run is capped rather than burning the full runner budget.
• Based on Task 1.1's findings, add a brief note to AGENTS.md (or the cicd skill) instructing the agent that a failed issue/PR create should stop and report the API error in a comment rather than retrying blindly.

🤖 Prompt for AI agents

Make sure that if a write ever fails again in future, the run stops cleanly and
visibly instead of looping — this closes off the failure mode diagnosed in Phase
1.

- Add a `timeout-minutes` setting to the `opencode` job in
`.github/workflows/opencode.yml`, so that a looping run is capped rather than
burning through the full runner budget.
- Based on the findings from Task 1.1's log investigation, add a brief note to
`AGENTS.md` (or alternatively the `cicd` skill) instructing the agent that a
failed issue/PR create should stop and report the API error in a comment, rather
than retrying blindly.

Research

OC is wired in through a single workflow, .github/workflows/opencode.yml, which fires on issue_comment and pull_request_review_comment (created), gates on COLLABORATOR/OWNER authors plus a /oc//opencode substring check, and hands everything to the third-party anomalyco/opencode/github@latest action.

That workflow grants only id-token: write — no contents, issues, or pull-requests write — and per the CHANGELOG (remove use_github_token to enable OpenCode app auth) it authenticates via the OpenCode GitHub App installation token, not the runner GITHUB_TOKEN.

Agent behaviour is documented in AGENTS.md plus trigger-loaded .opencode/skills/*/SKILL.md files; .opencode/skills/cicd/SKILL.md already owns the .github/workflows/ scope and the secrets/CI map.

There are no issue/PR templates, no root opencode.json, and no in-repo record of the OpenCode App's granted scopes.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Diagnose the actual failure behind the OC create/retry loop by inspecting real
Action run logs, then bank that knowledge as skill guidance — do not change any
workflow behaviour in this phase.

- Pull the failing run for the gradual-uptrend fix PR using `gh run list
--workflow=opencode.yml` and `gh run view <id> --log`. Grep the OC step output
for the issue/PR-creation call and its HTTP status (expect `403`/`404` on the
create call if it's a scope problem).
- Distinguish two candidate roots: (a) the App-token is missing Issues/Pull
requests write, vs (b) the runner `GITHUB_TOKEN` is being used but unscoped.
Record from the log lines which token OC actually used.
- Capture the exact error string and the retry cadence — this evidence must
inform Phase 4's loop-guarding work.
- Extend `.opencode/skills/cicd/SKILL.md` with a new short section titled
something like "Debugging OpenCode Action runs", covering: using `gh run
list`/`gh run view --log`, filtering to the `opencode` job, and inspecting
create-issue/create-PR API responses.
- In that same section, state explicitly that OC runs on the App installation
token (not `GITHUB_TOKEN`), so a `403` on write points to the App installation
scope, not the workflow `permissions:` block.
- Place this guidance in the `cicd` skill (not `debug`, which is scoped to the
pytrendy pipeline), since `cicd` already owns `.github/workflows/`.
===============================================================================

Task: 2

Tear down the permission wall identified in Phase 1 by widening scopes at both
layers that matter: the workflow's own permission block and the OpenCode App
installation.

- In `.github/workflows/opencode.yml`, add `contents: write`, `issues: write`,
and `pull-requests: write` to the existing `permissions:` block alongside
`id-token: write`. This is required regardless of the App-token outcome, since
the Phase 3 acknowledgement step runs on the runner `GITHUB_TOKEN` and needs
`issues`/`pull-requests` write to POST a reaction.
- Separately, confirm via GitHub App installation settings that the OpenCode App
is granted Contents, Issues, and Pull requests write on this repository — this
is the actual fix if Phase 1's log check shows the create call ran on the App
token.
- Document the required App scopes in `.opencode/skills/cicd/SKILL.md`, next to
the existing secrets list, since this configuration lives outside the repo and
would otherwise be lost again.
- Only fall back to setting `use_github_token: true` in `opencode.yml` if Phase
1 proves OC cannot use the App token for writes. If applied, this relies on the
widened permissions block above, but flag the trade-off clearly:
`GITHUB_TOKEN`-authored PRs won't trigger downstream CI.
===============================================================================

Task: 3

Fix the silent-failure class where the trigger job never fires — meaning no 👀
ever appears — by replacing the brittle substring check with robust, line-aware
parsing, and by making acknowledgement explicit rather than dependent on the
third-party action.

- The current logic (`startsWith(body,'/oc') || contains(body,' /oc')`) only
checks the very first character or space-prefixed occurrences. A quote-reply
body starts with `>` and places the command after a newline, so neither branch
matches — this is the root of the silent failure.
- In `.github/workflows/opencode.yml`, keep the existing cheap
`author_association` gate at job level, but move command detection into a
dedicated shell step. Read `github.event.comment.body` via `env:` only — never
string-interpolate it directly into `run:`, to avoid injection.
- Parse the body line-by-line: strip Markdown quote lines (those starting with
`>`), then match `/oc` or `/opencode` at a line start or on a word boundary.
Emit a `should_run` step output from this step.
- This approach naturally handles quote-prefixed comments, since the actual
command sits on its own unquoted line, while still correctly ignoring commands
that appear only inside quoted text.
- Add a new step, gated on `should_run`, that POSTs an `eyes` reaction to the
triggering comment using `actions/github-script`. Use the runner `GITHUB_TOKEN`
and the `issues`/`pull-requests` write scopes granted in Phase 2, and branch the
logic depending on whether the event is an issue comment or a PR review comment.
- Gate the existing `Run opencode` step on the same `should_run` output, so
detection, acknowledgement, and execution all stay consistent with one another.
===============================================================================

Task: 4

Make sure that if a write ever fails again in future, the run stops cleanly and
visibly instead of looping — this closes off the failure mode diagnosed in Phase
1.

- Add a `timeout-minutes` setting to the `opencode` job in
`.github/workflows/opencode.yml`, so that a looping run is capped rather than
burning through the full runner budget.
- Based on the findings from Task 1.1's log investigation, add a brief note to
`AGENTS.md` (or alternatively the `cicd` skill) instructing the agent that a
failed issue/PR create should stop and report the API error in a comment, rather
than retrying blindly.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!