Git

Use a Git step when a workflow needs repository evidence, a canonical delivery branch, or controlled integration after review. Git is separate from Valdr Tools: it is a workflow-runtime adapter with eight intentionally bounded actions, not a general shell or standalone MCP tool.

Actions

Required inputs

Valdr supplies clientRequestId for mutating Git steps and can supply projectKey from run scope. Author the remaining required values:

Valdr resolves the repository from projectKey; the project must have one registered repository or one repository marked as primary. Every action except commit also accepts repoId to select among multiple registered repositories. log accepts fromSha and a limit from 1 to 100. For task-session status or diff, supply taskKey and sourceSessionUlid together so Valdr can match the recorded worktree to its repository. Git object inputs must be full commit IDs; expectedRemoteSha may be absent when the remote branch must not exist yet.

Diff evidence

Diff evidence requires Git 2.41 or newer.

The diff action records the repository, exact base and head commits, and a digest of their comparison. It retains those commits in Git so later branch movement or worktree removal does not change the evidence. Patch text is not included in the workflow result. Both inputs must identify commits; an uncommitted working tree is not an approval snapshot.

Review proposed changes

At a pull request approval, choose Review and decide, then open Changes. The preview compares the frozen commits for that proposal, so you do not need to find the implementing session. Switch back to Proposal to edit the title, description, or draft setting; your edits stay in the dialog.

Use the file list to choose a change. Large file lists and patches have page controls; a Partial file preview shows only the labeled byte range. Binary files show change metadata rather than their contents. Renames and file permission changes are shown even when there are no text hunks.

If the recorded evidence cannot be loaded or verified, publishing is disabled and the dialog offers a read retry. You can still reject the proposal or close the dialog. The preview does not require you to mark every file as viewed.

Create a delivery branch

For example, a workflow can open a plan branch without switching the active checkout:

- key: create_plan_branch
  name: Create Plan Branch
  kind: tool
  tool:
    id: git
    action: branch_create
  inputs:
    projectKey: "${workflow.inputs.projectKey}"
    branchName: "valdr-plan/${workflow.inputs.planKey}"
    canonicalKey: "${workflow.inputs.planKey}"
    sourceBranch: "${workflow.inputs.baseBranch}"
    expectedBaseSha: "${workflow.inputs.expectedBaseSha}"
  outputs:
    outcome: "$.normalized.outcome"
    branchName: "$.normalized.branchName"

The workflow can accept created or existing and block on drift or a checked-out target. This makes retries predictable without silently replacing a branch that now points somewhere else.

Safety boundaries

Git actions resolve only registered project repositories or task sessions already recorded by Valdr. Branch creation, merge, and push compare the recorded identity and expected commits before changing a ref. They never fetch, switch checkouts, or run commit hooks. Push is a lease-guarded compare-and-swap on expectedRemoteSha. Most drift results are routable outcomes; push reports remote_drift or rejected as a tool error, so the step follows its failure policy.

Next step

Read GitHub to publish an approved branch as a pull request, or From Idea to Verified Sprint to see plan branching and reviewed task integration in a complete workflow.