mirror of
https://github.com/xlionjuan/searxng-mcp-go.git
synced 2026-11-17 04:17:51 +00:00
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.
195 lines
8.5 KiB
Markdown
195 lines
8.5 KiB
Markdown
# 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 `gh` locally.
|
|
- PR creation and commenting may be handled by OpenCode's GitHub integration
|
|
instead of direct `gh pr create` calls.
|
|
- 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_pr` is false, do not modify files and do not open PRs.
|
|
- If `allow_pr` is 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 `.gitignore` unless 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.md` and
|
|
`docs/agents/test-server.md`.
|
|
|
|
The following general rules are narrowed for GitHub Actions OpenCode:
|
|
|
|
- `gh pr create` is 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 `gh` only when the workflow grants the needed permission and says
|
|
to do so.
|