Skip to content
GitmoapdocsBeta
Concept· Why does it work like that?Draft

Dry runs

Overview

Some changes are hard to predict and costly to get wrong — who gains access when you grant a role, whether a commit will land on a protected branch, what publishing a component version does to the pipelines that use it. Operations like these accept dry_run=true: the request runs the checks the real one would and answers with what would happen, and nothing is written.

In the CLI the same switch is --dry-run. Preview, read the answer, then send the identical request without it.

How it works

Which operations take it

AreaOperationsWhat the preview tells you
Accessgiving, changing and revoking access; setting and removing a limit; switching inheritance on or offeach person whose access would change, with the permissions they would gain and lose and their role before and after, and how many groups and repositories inherit the change
Teamsadding or removing a member; deleting a teamwhat each person would gain or lose
Custom roleschanging a rolethe permissions gained and lost, and how many grants use the role
Commitscommitting files through the API; resolving a merge request's conflictswhether it would land, every reason it would not, the files that changed since you read them, and the pipelines it would start
Pipeline componentspublishing a version; re-pinning the pipelines that use onethe lowest version number the change permits, and what it would do to the pipelines referencing the component
AI organizationspublishing a revisionthe agents it would hire and retire

The API reference shows the dry_run parameter on each of them.

What comes back

A preview answers 200, where the real request answers with its own success — 201 for one that creates something, 204 for a delete. Where the real request returns a body, the preview usually comes back in the same shape, so the code that reads one reads the other. A delete's preview describes what would be taken away. A commit or conflict-resolution preview has a shape of its own, led by allowed and refusals.

Refusals

A dry run needs the same token scope as the real request, and goes through the same checks: your access, whether you may confer what you are handing out, whether the request is well formed. If one fails, the preview is refused with the same status and error the real request would get. Publishing a component version under a number too low for the change is refused rather than reported, for example, with the lowest number the change permits.

Commits and conflict resolution are the exception, because a form wants every problem at once. Their preview answers 200 even when the commit would be refused: allowed is false, and refusals lists every reason, each naming the part of the request it is about — the branch, the message, or one file change — so a page can show them all before anyone presses the button. A repository you cannot see still answers 404.

Nothing is written

A preview creates nothing, changes nothing, sends no event and consumes no quota. A preview of a change to access, teams or roles, or of a commit, leaves no record in the audit log either — a log that listed previews would say access changed when it did not. So a dry run is safe to repeat as often as you like, and cheap enough to run as a form changes.

A preview is computed from the facts as they stand the moment you ask. It reserves nothing: if someone changes access, pushes to the branch or publishes a version in between, the real request makes every check again and may answer differently. If time has passed, preview again before relying on it.

Related