Repository inspection
Rivet provides a common read interface for GitHub.com, Bitbucket Cloud and GitLab.com. It identifies repositories, reads branches and pull/merge requests, and records checks and reviews without turning those observations into permission to deliver.
Inspect from your project
From a configured Git project, including a nested folder:
rivet repositories inspect
rivet repositories inspect --review=14The first command reads repository metadata. The second captures a pull request (GitHub/Bitbucket) or merge request (GitLab), its head commit, checks and review observations. Use the number from the selected repository.
If no saved publishing choice resolves multiple repositories, or several configured providers match, select them explicitly:
rivet repositories inspect --remote=upstream --provider=team-github --review=14 --jsonRivet does not assume that origin is the publishing target. An explicit --project=/absolute/project is available when running elsewhere. These commands perform network reads; rivet integrations check reports configuration readiness unless you explicitly add --live.
Bitbucket SSH hostname
Use git@ssh.bitbucket.org:<workspace>/<repo>.git for new Bitbucket Cloud SSH remotes. Rivet recognizes this hostname (including ssh://git@ssh.bitbucket.org/...) and the legacy git@bitbucket.org:... form as the same repository identity. The canonical web/PR identity remains https://bitbucket.org/<workspace>/<repo> and the REST endpoint remains https://api.bitbucket.org/2.0. Rivet does not rewrite your Git remote or SSH trust configuration.
Atlassian's SSH migration notice schedules brownouts of SSH access through bitbucket.org from November 12, 2026, with refusal of all SSH connections to that hostname after December 10, 2026. HTTPS connections are unaffected. Follow the notice to migrate SSH remotes, known hosts and CI/network configuration; reverting to the old SSH hostname is not a lasting workaround.
Choose a publishing remote during setup
rivet setup previews locally configured Git remotes without network access. It proposes a single supported remote; when several names are available, it asks you to choose while applying setup in an interactive terminal. It never assumes origin is the publishing destination.
For an explicit choice, including scripts and JSON output:
rivet setup --remote=upstream
rivet setup --remote=upstream --writeThe preview shows the selected name and canonical repository URL. Applying setup stores them in repository.remote in .rivet/project.yaml. Other project settings, comments, provider files and project protocols are preserved. Local-only projects do not need a publishing remote.
Repository inspection and delivery preparation reuse this choice. A per-command --remote selects another destination for that operation without rewriting the saved choice or authorizing a write. Provider scope, review and merge approvals still apply separately.
If the saved remote disappears or points to a different repository, Rivet stops and asks you to review the choice again. Run setup with an explicit remote and inspect its preview before applying the replacement. Cancellation and conflicting changes during setup leave the selection unwritten.
Configure read access
Add an entry to the existing providers list in .rivet/providers.yaml:
- id: team-github
kind: git-ci
mode: read-only
transport: direct-api
capabilities: [repository-read, checks-read]
endpoint: https://api.github.com
projectIds: [your-project-id]
resourceIds: [your-team/your-repository]
credentials:
tokenEnv: RIVET_REPOSITORY_TOKENUse the project's actual ID and repository path. Set the referenced environment variable outside tracked configuration. The inspection CLI accepts a bearer token; it does not copy credentials from another application. Use a provider-issued token with read access to the selected resources. Tokens and credential values are excluded from output. For Bitbucket Cloud REST reads and standalone review:
- Store the complete token in the environment variable named by
credentials.tokenEnv(oraccessTokenEnv/apiTokenEnv); Rivet sends it asAuthorization: Bearer <token>. - Set
endpointto exactlyhttps://api.bitbucket.org/2.0. - Grant read access to repositories and pull requests. For scoped API tokens, the minimum scopes are
read:repository:bitbucketandread:pullrequest:bitbucket. - Scoped Atlassian API tokens supported as Bearer credentials can be used; OAuth and repository access tokens with the required access are also supported. See Atlassian's API-token authentication reference.
Check access with rivet integrations check --live or rivet doctor --live (add --json for structured output). Check that copying/pasting preserved the whole token; Rivet cannot infer validity from token length. A 401 means the provider rejected the credential; check expiry, truncation and token compatibility. A 403 means insufficient scope or another access restriction. No token values or provider response bodies appear in diagnostics. See live-check limits.
| Provider | API endpoint | Repository scope example |
|---|---|---|
| GitHub.com | https://api.github.com | team/repo |
| Bitbucket Cloud | https://api.bitbucket.org/2.0 | workspace/repo |
| GitLab.com | https://gitlab.com/api/v4 | group/subgroup/repo |
Repository inspection requires repository-read; review inspection also requires checks-read. Disabled, out-of-project, out-of-repository and mismatched endpoint entries are not selected. Credentials must be present before any provider request. SSH or HTTPS Git remotes identify the repository; API reads use HTTPS.
Capability and qualification matrix
| Capability | GitHub.com | Bitbucket Cloud | GitLab.com |
|---|---|---|---|
| Repository and branch reads | Implemented | Implemented | Implemented |
| Pull/merge request identity and head SHA | Implemented | Implemented | Implemented |
| Commit checks/status observations | Implemented | Implemented | Implemented |
| Review observations | Implemented | Implemented | Implemented |
| Common interface writes | Unavailable | Unavailable | Unavailable |
| Separate HTTPS branch publication | Implemented, create-only | Implemented, create-only | Implemented, create-only |
| Separate native review creation | Implemented | Implemented | Implemented |
| Separate review title/description updates | Implemented | Implemented | Implemented |
| Separate native merge | Implemented for documented policies | Unavailable | Implemented for documented policies |
| Project-configured deployment | GitHub Actions executor | Unavailable | Unavailable |
| Public repository/branch read smoke | Passed | Passed | Passed |
| Public review inspection smoke | Passed on Rivet PR #14 | Pending | Pending |
| Authenticated sandbox and delivery qualification | Pending | Pending | Pending |
Public smoke checks on 2026-09-25 read Agilno-Tech/rivet, atlassian/atlassian-frontend-mirror and gitlab-org/gitlab without credentials. The GitHub check also inspected Rivet PR #14. These bounded reads do not establish private-repository access or complete delivery support.
The existing lower-level GitHub adapter retains its governed operations. The common repository interface is read-only. MCP and local CLI repository execution, custom API hosts, GitHub Enterprise, Bitbucket Data Center and self-managed GitLab are not qualified through this interface.
For local delivery preparation and the delivery service, see delivery lifecycle. Separate delivery executors support GitHub/Bitbucket PR and GitLab MR creation for already published verified branches, separately approved title/description updates for all three providers, plus GitHub/GitLab merges under documented bounded policy subsets. Create-only HTTPS branch publication is implemented separately for all three providers. Merge Bitbucket PRs manually in Bitbucket. Automatic merging is not available; live qualification remains pending.
Interpreting results
An inspection is a bounded observation at a particular time, not an atomic provider snapshot. Reviews and checks can change after they are read. It rechecks the request head after collecting related evidence and fails if that head changed. Checks from a different commit cannot count as current evidence. A review observation without a provider-supplied commit binding cannot prove approval of the current commit.
No checks is not a passing required-check gate. Observed approvals are not a substitute for branch protection, required reviewers, project policy or explicit delivery authority. Repository inspection does not merge, deploy, update a tracker or mark a Rivet task delivered.
Pagination is bounded. Access errors, missing branches, rate limits, malformed results and inconsistent snapshots stop inspection rather than producing partial success. Retry after correcting access or waiting for provider availability; inspect again after a new commit.
Provider references
- GitHub REST checks and pull request reviews.
- Bitbucket Cloud commit statuses and pull requests.
- GitLab commits and merge request approvals.
Branch names for features and fixes
Rivet chooses the task's branch pattern during planning and includes it in the approval. Terminal and coding-harness workflows use the same choice, so a bugfix can start on fix/... or your repository's bugfix/... convention.
During initial setup, Rivet suggests familiar prefixes from local and remote-tracking branches when the prefix for a task type is unambiguous. Review these suggestions against your contribution guide. It does not fetch branch history or interpret free-form instructions as executable configuration. For an existing setup, configure the conventions in .rivet/project.yaml:
repository:
defaultBranch: main
branchPattern: feature/{slug}
branchPatterns:
feature: feature/{slug}
bugfix: bugfix/{ticket}/{slug}
hotfix: hotfix/{slug}
chore: chore/{slug}branchPatterns overrides the fallback for each task type. Supported types are feature, bugfix, hotfix, chore, docs, refactor, test and ci. {slug} includes the task name and unique run suffix. Optional {ticket} requires a sourced Jira/Linear ticket ID. {type} expands to the usual prefix (fix for bugfix). Use patterns without {ticket} for free-text tasks.
The original generated fallback feature/{slug} now selects the matching type prefix, including fix/ for bugfixes. Other custom fallback patterns, such as team/{slug}, remain unchanged. Set an explicit per-type pattern if your team wants a different convention. Existing approved runs retain their original branch choice.
A sourced issue type takes precedence over a planner's classification. Jira bug types and recognized Linear labels can supply it; a harness context bundle can supply content.workType. Clear title prefixes such as Fix login timeout are also recognized. For other tasks, the planning harness classifies the work before approval. For a Markdown request, you can make the choice explicit:
# Login times out
## Work type
bugfix
## Acceptance criteria
- Existing users can sign in successfully.Before activation, check the proposed branch pattern. If it conflicts with the repository's contribution instructions, update the configuration and create a new proposal before starting work. Do not rename an active Rivet branch behind its saved state.