Read-only stage posts

A read-only stage cannot commit code. It can still post comments and reviews. A review stage uses this to leave its findings on the pull request it reviews. The relay allows only a short list of writes. It sends them as the GitHub App or a GitLab bot, never as a person.

What a read-only stage can post

On a repository in the sandbox’s list, the stage can:

• Comment on a GitHub pull request or issue (gh pr comment, gh issue comment).
• Post a GitHub review with the event COMMENT or REQUEST_CHANGES (gh pr review --comment, gh pr review --request-changes).
• Post inline review comments and replies to them.
• Edit a comment that the same App identity wrote. It cannot edit any other comment.
• Post a note or a discussion reply on a GitLab merge request or issue.

A repository marked read only on the repository list still accepts these posts. A comment changes no code. Read only means no push.

What it can never do

The relay refuses these from a read-only stage, on every repository:

• Approve. A GitHub review with the event APPROVE is refused. A GitLab approve and unapprove are refused. An approval can satisfy branch protection, so an agent must not give one.
• Change code. Contents, branches, tags, refs and merges are refused.
• Change state. Closing, reopening, labels, assignees and reviewers are refused. Dismissing a review is refused.
• Run a GitLab quick action. A note line that starts with /, such as /approve, /merge or /close, changes state. The relay refuses the whole note.
• Reach another repository. A repository outside the sandbox’s list is refused.
• Send parameters in the URL. A post must send its parameters in a JSON body. A request with a query string is refused, because the relay checks only the body.

A GraphQL request is checked field by field. One refused mutation refuses the whole request. The relay also looks up every node the mutation names. All of them must belong to one listed repository.

A stage that can write code keeps its existing rules. This page covers read-only stages only.

The risk: untrusted text

A review or plan agent reads text that other people wrote. Issue text, pull request text and comments can all carry instructions meant to steer the agent. This is prompt injection. A steered agent could post a misleading comment, or post many comments.

The safeguards bound the harm:

• Listed repositories only. The agent cannot post anywhere else.
• No approval and no state change. The worst post is a comment or a request for changes.
• App or bot identity. Every post shows the App or bot as its author. A reader can tell it from a person. A personal credential is refused unless you turn on the workspace setting below.
• A per-session cap. One session may relay at most 20 social writes by default. The next one gets 429. Set CH_GITPROXY_SOCIAL_WRITE_CAP on the device to change the cap. A value of 0 turns the feature off.
• An audit event. Each relayed post adds a task.host_social_write event to the task timeline. It names the repository, the number, the kind and the link. You can subscribe to it. If the server cannot record events, the relay refuses to post.
• The token stays outside the sandbox. The server mints the token and the device adds it to the request. The agent never sees it.

Treat a posted comment as agent output, not as a decision. Do not let a bot comment replace a human review.

Set up

The GitHub App needs Pull requests: write and Issues: write. The App needs them on the installation, besides the contents permission. See Connecting the GitHub App. Without them, the server cannot mint a token for these posts, and the relay refuses them. The relay never falls back to a wider token.

For GitLab, the workspace needs a GitLab connection with the api scope and the Maintainer role. The server then mints the token. See Server-minted tokens.

Allow a personal credential

If a device has only a pooled credential, the relay refuses the post. An owner or admin can allow it. Open Settings → General and turn on Allow read-only stage posts with a personal credential. You can also run:

ch workspace edit <workspace> --social-personal-identity true

The setting is off by default. It applies to that workspace only. With it on, a post may appear to come from a person. Approvals stay refused.