# Git
{{< tier level="sovereign" note="Git steps give workflows review-aware, ref-safe local delivery operations." >}}

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](../tool/): it is a workflow-runtime adapter with eight intentionally bounded actions, not a general shell or standalone MCP tool.

## Actions

| Action | Use it to |
| --- | --- |
| `status` | Record a repository or task-session snapshot |
| `diff` | Retain two exact commits and record a compact evidence receipt with a complete diff digest |
| `log` | Read bounded history from an exact commit or validated local branch |
| `remote_status` | Record the remote identity and exact base and head refs without fetching |
| `branch_create` | Create one canonical task or plan branch from an expected commit |
| `commit` | Commit the exact delivery recorded by a completed, approved task workflow |
| `merge` | Fast-forward an unchanged local target branch to an exact reviewed commit |
| `push` | Push one exact local branch through a frozen remote identity and ref lease |

## Required inputs

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

| Action | Required values |
| --- | --- |
| `status` | `projectKey` |
| `diff` | `projectKey`, `fromSha`, `toSha` |
| `log` | `projectKey`, `ref` |
| `remote_status` | `projectKey`, `remoteName`, `baseBranch`, `headBranch` |
| `branch_create` | `projectKey`, `branchName`, `canonicalKey`, `expectedBaseSha` |
| `commit` | `projectKey`, `taskKey`, `sourceSessionUlid`, `deliveryRunUlid`, `message` |
| `merge` | `projectKey`, `sourceSha`, `targetBranch`, `expectedTargetSha` |
| `push` | `projectKey`, `remoteName`, `branchName`, `expectedRemoteUrlDigest`, `expectedLocalSha`, `expectedRemoteSha` |

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:

```yaml
- 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.

{{< callout type="info" >}}
The `commit` action is intentionally narrower than a general Git commit. It accepts only a completed delivery run with approved review evidence and commits the exact paths recorded by that delivery.
{{< /callout >}}

## Next step

Read [GitHub](../github/) to publish an approved branch as a pull request, or [From Idea to Verified Sprint](../../idea-to-sprint/) to see plan branching and reviewed task integration in a complete workflow.