The system does not inject the PR number into the agent's context. Document how to discover it (gh pr view primary, gh pr list fallback) and require verification before editing. Also add cross-reference in opencode-github-actions.md emphasising that guessing the PR number will target the wrong PR.
8.5 KiB
OpenCode in GitHub Actions
Use this guide only for OpenCode runs executed by this repository's GitHub
Actions workflows, such as .github/workflows/opencode.yml and
.github/workflows/opencode-doc-code-alignment.yml.
These rules are a narrow compatibility layer for the OpenCode GitHub Action.
They do not replace the general repository rules in AGENTS.md; they identify
which general pull-request rules do not map cleanly to the Action runtime.
Scope
GitHub Actions OpenCode runs are different from local or interactive agents:
- They are invoked by workflow events or manual workflow dispatch, not by a
user running
ghlocally. - PR creation and commenting may be handled by OpenCode's GitHub integration
instead of direct
gh pr createcalls. - Some generated PR metadata, especially PR titles, can be difficult for the agent to control because of current Action/runtime behavior.
- The workflow-provided git identity may be controlled by the Action and must not be guessed or overwritten by the agent.
When a rule in this file conflicts with the general PR workflow, this file wins for GitHub Actions OpenCode runs only.
Invocation
The comment-triggered OpenCode workflow runs only when an authorized comment
contains /oc or /opencode. Comments without those trigger words do not start
OpenCode.
Do not set a fixed with.prompt in .github/workflows/opencode.yml. The
OpenCode GitHub Action treats that input as an override for the default
comment-driven prompt, so a fixed prompt can cause OpenCode to ignore the
actual /oc ... user request. Put durable instructions in AGENTS.md and
docs/agents/ instead.
The documentation/code alignment workflow is manually dispatched. Follow its workflow inputs first:
- If
allow_pris false, do not modify files and do not open PRs. - If
allow_pris true, open a PR only for narrow, unambiguous fixes supported by repository evidence.
GitHub Operations
OpenCode's GitHub Action infrastructure owns only the operations it supports:
- Posting comments
- Pushing commits
- Opening PRs
Prefer the OpenCode GitHub integration for those operations. In particular, use it for PR creation when the workflow allows PRs.
Use gh where the workflow or prompt explicitly requires an operation that the
OpenCode integration does not support. The documentation/code alignment workflow
is the known exception: it grants issues: write and explicitly requires
gh issue create because OpenCode's GitHub integration does not provide native
Issue creation in that workflow.
The general rule that PR agents must always use gh pr create is waived for
GitHub Actions OpenCode. If the OpenCode GitHub integration creates the PR, that
is sufficient.
Do not substitute a /pull/new/... URL for an actual PR. If neither OpenCode's
GitHub integration nor gh pr create can create the PR, report the exact
failure and stop.
Automatic Push Safety
Treat the OpenCode GitHub Action working tree as a write boundary. The Action infrastructure checks whether the local branch is dirty after the agent responds; if it is dirty, the infrastructure may create a commit and push it automatically. This can happen even when the user asked only a question.
Before doing anything that can modify files, decide whether the user explicitly asked for a content change.
For read-only requests, such as investigation, explanation, verification, review, triage, or "is this safe?", the agent must not leave any file, submodule, generated artifact, dependency file, cache output, or formatting change in the working tree. Use read-only commands where possible. Avoid commands that update submodules, rewrite generated files, run formatters, run tidy commands, or otherwise normalize the checkout unless the user asked for a change.
If a read-only task dirties the working tree anyway, restore the worktree to its initial state before finishing. If it cannot be restored safely, stop and report the exact dirty files instead of allowing the infrastructure to auto-push them.
For write requests, keep changes limited to the requested scope and verify the diff before the run finishes. Never rely on the infrastructure's automatic commit step as a substitute for checking what will be pushed.
PR Titles and Bodies
Write PR bodies in English and include durable review context:
- Summary
- Documentation impact
- Tests or verification run
- Linked issue(s), when applicable
- Known limitations or follow-up work
PR titles must follow the repository PR title policy whenever the runtime
exposes enough control to create or update PR metadata. Read
docs/agents/pull-requests.md#pr-title-policy before setting or editing a PR
title. Do not use filenames, issue fragments, agent status, session names, or
titles without an allowed semantic prefix as PR titles.
If the OpenCode GitHub Action produces an initial PR title that cannot be reliably controlled, treat that specific creation-time title as an Action limitation, not a task failure. This exception is narrow: when a reliable edit path exists, or when the agent is already updating PR metadata, the agent must bring the PR title back into compliance before reporting the metadata work complete. If a title-related status check is failing, inspect the check message and make the new title satisfy that policy.
When editing PR metadata, the agent must discover the PR number from the
environment — the system does not inject it. Follow the "Discover PR number"
step in docs/agents/pull-requests.md before running gh pr edit. Do not
guess the number; guessing will target the wrong PR.
Automatically appended OpenCode session links, social-card images, and GitHub Actions run links are allowed as supplemental metadata. They must not replace the normal PR body sections.
Git Identity
Do not configure git author or committer identity from inside the run. In particular, do not derive an identity from:
- The tool name
- The Action name
- The repository name
- A guessed GitHub noreply address
- A prior disputed commit
If the workflow-provided identity is missing, ambiguous, or known to be wrong,
stop and report the exact evidence. Do not set user.name, user.email,
GIT_AUTHOR_*, GIT_COMMITTER_*, or EMAIL to make a commit succeed.
This rule exists because issue #32 documented an OpenCode investigation where a
GitHub Actions run used a squatted-looking [email protected]
identity. That kind of value is evidence of a problem, not a source of truth.
For commits created by the OpenCode GitHub Action, the acceptable pattern is an explicit, provider-owned bot/app identity or a reviewed repository-owner identity supplied by the workflow. Do not infer identity safety from a commit headline or PR body alone.
PR #289 is useful as a PR-body example: it provides a concrete step summary,
verification commands, a linked issue, and supplemental OpenCode/GitHub run
links. Its commit headline, Config plumbing refactor (A/B+C), is concise and
change-focused; that is the useful part of the commit metadata for this guide.
Verification
GitHub Actions OpenCode must follow the same AI-agent completion gate as every
other agent. Before opening a PR, updating a PR, or reporting a code-changing
task complete, run the non-E2E workflow checks listed in
docs/agents/verification.md.
If the workflow prompt specifies stronger verification, follow the prompt. If a
tool is unavailable in the Action environment, use the documented fallback from
docs/agents/verification.md and state the limitation in the PR body or final
comment.
For read-only audit workflows, do not run broad local verification unless it is needed to support a finding.
Relationship to Other Agent Rules
The following general rules still apply:
- Do not modify
.gitignoreunless explicitly asked. - Do not change the MCP handler's User-Agent header.
- Use patch-style edits for existing files.
- Keep documentation in English.
- Update related documentation when behavior or workflow rules change.
- Follow the E2E and test-server boundaries in
docs/agents/e2e-tests.mdanddocs/agents/test-server.md.
The following general rules are narrowed for GitHub Actions OpenCode:
gh pr createis not mandatory when OpenCode's GitHub integration creates the PR.- PR title policy is best-effort when the Action runtime does not provide reliable title control.
- GitHub operation routing follows the workflow prompt: OpenCode's integration
handles comments, pushes, and PRs; unsupported operations such as Issue
creation use
ghonly when the workflow grants the needed permission and says to do so.