Work with pull requests and Pipelines
Read a PR, publish your review, merge it, or investigate a build. These examples use the guided commands in the current Mac and Linux releases. On Linux, use the absolute executable path printed during download in place of rovito in every command below.
Sign in first. Commands use your active login; add --profile NAME to use another. Repositories do not choose their login automatically. See accounts and workspaces to keep work and personal logins separate. Replace your-workspace/your-repo with the names in your Bitbucket URL.
Inside a Git checkout, read commands can use an unambiguous Bitbucket remote. These examples name the repository explicitly so they also work outside a checkout. For a saved default for writes, see repository binding. A default is not a restriction on the token's access.
Using Windows or an older Linux archive? Follow its versioned CLI guide; it does not have these guided choices.
Read a pull request
If you use work and personal accounts, remember a login for this repository first. rovito context show explains which account a CLI command will use. For an agent connection, check context_get instead; its account stays pinned to the connection.
rovito pr list --repo your-workspace/your-repoChoose a PR from the list and replace 42 in the following commands with its number. An empty list means there are no open PRs.
rovito pr view 42 --repo your-workspace/your-repoRead the discussion:
rovito pr comment list 42 --repo your-workspace/your-repoRead the code changes:
rovito pr diff 42 --repo your-workspace/your-repoCollect structured context for a review
rovito pr context 42 --repo your-workspace/your-repo --output jsonThis combines review information with completeness and omission fields. Check those fields before assuming you have every diff or comment. Follow the returned continuation arguments for relevant missing material, and report anything you cannot obtain.
This workflow requires a version that returns a snapshot and supports expected read flags; older versions may lack them. Keep the returned snapshot and use its continuation arguments with the original profile, repository UUID and both expected hashes. A detected head change fails before content is printed; start a fresh context and review the changes. Same-repository diffs target both commits. Fork fallback checks observed heads and can miss a change that reverts between checks. Comments, tasks and checks remain live.
Comment and review
Everyday development and Review and comment logins allow review work, subject to your Bitbucket permissions. Check permissions if a command is denied.
Post a comment after reading the PR. Replace the example text with your feedback; this command publishes it.
rovito pr comment create 42 --repo your-workspace/your-repo --body 'Please cover the empty-input case.'The result identifies the new comment. Use the comment-list command above to read it back.
To approve a PR, choose it in the terminal and confirm the current version:
rovito pr review approve --repo your-workspace/your-repoApproval records your review; it does not merge the PR. If changes are needed instead, use:
rovito pr review request-changes --repo your-workspace/your-repoFor replies, tasks, editing and structured inline findings, see the CLI guide.
Merge a reviewed PR
Use an Everyday development login with merge access in Bitbucket:
rovito pr merge --repo your-workspace/your-repo --waitChoose the PR, inspect its checks and confirm. Rovito looks up the current commits and repository ID. --wait waits for the PR to be observed as merged; queued is not yet merged. If it times out, check that same PR rather than submitting another merge.
These prompts are for people in a terminal. Scripts need explicit commit hashes, repository ID and --yes; see scripted merges. Confirmation never disables those checks.
Run a Pipeline and check its result
The repository needs Pipelines enabled and a bitbucket-pipelines.yml. Starting a run may consume build minutes. With Everyday development access, run:
rovito pipeline run --repo your-workspace/your-repoChoose the branch and Pipeline, then confirm. The result gives the new run's UUID and build number. Accepted means it was started, not that it passed.
To find an existing run instead:
rovito pipeline list --repo your-workspace/your-repoReplace #123 with the build number from the result. Keep the quotes so your shell does not treat # as a comment.
rovito pipeline status '#123' --repo your-workspace/your-repostatus reports the current state. Its command succeeds even if the build failed. To wait and return success only when the build succeeds:
rovito pipeline wait '#123' --repo your-workspace/your-repoA failed build returns exit 1; a wait timeout returns exit 8. Continue observing the same run after a timeout.
Read the relevant step's logs
rovito pipeline log read '#123' --repo your-workspace/your-repoChoose a named step. This reads up to 1 MiB by default, not necessarily the whole log. Use --offset and --limit for a specific byte range; see rovito pipeline log read --help. To watch output with a continuation command instead:
rovito pipeline log follow '#123' --repo your-workspace/your-repoFollowing stops at a byte, time or idle limit. Use the returned command to continue from the last offset. Logs can contain secrets; do not paste them into a public report. Terminal output is sanitized, but redirected logs and diffs contain exact bytes.
For explicit step IDs, secured variables, stopping runs and other trigger types, see Pipeline options.
Give your agent a specific task
After connecting through MCP, replace the build number and try:
Use Rovito to check its connected login, then check Pipeline #123 in acme/service. If it failed, find the failed step and read the relevant log excerpts. Explain what failed and tell me if anything could not be checked. Do not rerun or stop anything.
Replace #123 with your build number. The agent uses pipeline_get, then pipeline_steps_list to find step UUIDs, and pipeline_logs_read for a small log range. It can do this entirely through MCP, without terminal access.
The step list returns 25 entries by default. If has_more is true, the agent uses the returned pipeline_uuid and next_cursor to request another page. Log reads continue from next_offset. An empty step list does not mean a run passed; a running Pipeline may not have created its steps yet. If a read is denied or unavailable, the agent should explain the limit, not start another run.
The agent cannot find the step-list tool
Update Rovito and restart its connection in your agent client. This read tool needs no new write permission or configuration. Use a current Mac or Linux release that includes pipeline_steps_list. Older Linux archives and the Windows download lack it. See the Pipeline tool examples and limits.
For reviewing and publishing through MCP, follow the agent review example.
Continue safely after a problem
A merge is queued or its wait timed out
Use rovito pr view 42 --repo your-workspace/your-repo with the original PR number. Only MERGED confirms completion. Follow the result's reconciliation instructions; do not send another merge just to check its state.
A write has an unknown or partial result
Read the outcome and next steps in the error before trying again. Unknown means the request may have succeeded. Rovito supplies read commands with the original login and repository, such as rovito pr comment list 42 --repo acme/service --profile work. Use the values from your error, not these examples. A list is only a page; a missing comment does not prove it was never posted.
A partial review keeps its completed IDs and lists the remaining actions in order. Check the first pending action's result; later pending actions were not sent. Do not repeat the whole review or start another Pipeline blindly. See the error example and recovery instructions.
The repository or commits changed
Check rovito context show --repo your-workspace/your-repo and read the PR again. Confirm that it is the intended repository and review the new commits. Do not remove identity or commit checks to force a write through.
A command is forbidden or login failed
Use login troubleshooting. Check the selected login and Bitbucket permissions. Do not change every permission to Administration or replace the original login method.
Find less common commands
Add --help to any command. It works without signing in and explains the inputs and examples. Start with rovito pr --help or rovito pipeline --help.
The CLI reference covers text files, tasks, JSON, exit codes, completion and the general API commands. The agent reference covers structured publication and secret references.