Skip to main content

`repo.push`

The "push the changes you just committed" pack. Caller supplies a clone_path (from repo.fetch); the pack discovers the remote URL via git remote get-url, resolves credentials from the vault (SSH key by host-match or HTTPS PAT by name), runs git push, and shreds the credential on exit. Closes the Phase 5.5 code-edit loop: repo.fetch → fs.read → fs.patch → cmd.run → git.commit → repo.push.

force defaults to false. When true, the pack uses --force-with-lease (not --force) — pushes are blocked if the remote moved under you, protecting against races between concurrent agent runs or human operators.

Inputs

Field	Type	Required	Default	Notes
`clone_path`	`string`	yes	—	From `repo.fetch`.
`remote`	`string`	no	`origin`	Remote name. The pack discovers its URL via `git remote get-url <remote>`.
`branch`	`string`	no	auto-detected	Branch to push. Falls back to `git symbolic-ref HEAD`; errors if the working tree is detached.
`force`	`boolean`	no	`false`	When true, uses `--force-with-lease` (refuses if remote diverged). Logged in the audit trail.
`credential`	`string`	no	—	Vault credential name. Required for private HTTPS pushes. SSH pushes resolve by host-match (no name needed).
`_session_id`	`string`	yes (chained)	—	From `repo.fetch`.

Outputs

Field	Type	Notes
`url`	`string`	Discovered remote URL.
`remote`	`string`	Echo.
`branch`	`string`	Branch that was pushed.
`commit`	`string`	HEAD SHA on the local clone after push.
`credential`	`string`	Vault record name actually used (or `""` for public-write — rare).
`forced`	`boolean`	Whether the push was a force-with-lease.

Vault credentials needed

Same as repo.fetch: SSH key (host-match) or HTTPS PAT (named credential). Public-write isn't a normal flow — every realistic push needs auth.

Use it from your agent (OpenClaw chat-UI worked example)

Prompt (sent in OpenClaw chat UI / openclaw-cli agent):

Clone https://github.com/tosin2013/helmdeck-pack-doc-fixtures.git via helmdeck__repo-fetch with credential=github-token, then write a file via helmdeck__fs-write at path demo-pr-c-push.md content "# PR-C demo push" using the returned _session_id and clone_path, then commit via helmdeck__git-commit with message "demo: PR-C repo.push capture" and all=true, then push via helmdeck__repo-push with credential=github-token. Tell me the post-push commit SHA and the remote URL.

Tool call (18 calls, no failures):

{
  "name": "helmdeck__repo-fetch",
  "arguments": {
    "url": "https://github.com/tosin2013/helmdeck-pack-doc-fixtures.git",
    "credential": "github-token"
  }
}

Pack response (truncated):

{"pack":"repo.fetch","version":"v1","output":{"clone_path":"/tmp/helmdeck-clone-ammyks","commit":"176ae60069d18992d1b44b7b412f781e632ab788","credential":"github-token","doc_hints":["README*","docs/**/*.md","docs/**/*.adoc","docs/**/*.rst","content/**/*.md","content/**/*.adoc"],"entrypoints":[],"files":1,"readme":{"content":"# helmdeck-pack-doc-fixtures\n\nScratch repo for OpenClaw transcript captures during [helmdeck](https://github.com/tosin2013/helmdeck) pack documentation work.\n\nIssues, comments, and releases here are intentional artifacts produced while documenting `github.*` capability packs. **They are not real bugs.** If you landed here from a search expecting upstream helmdeck triage, head to the [main repo](https://github.com/tosin2013/helmdeck/issues).\n\n## How this repo gets 
  ...[truncated]

{
  "name": "helmdeck__fs-write",
  "arguments": {
    "clone_path": "/tmp/helmdeck-clone-ammyks",
    "path": "demo-pr-c-push.md",
    "content": "# PR-C demo push"
  }
}

Pack response (truncated):

{"pack":"fs.write","version":"v1","output":{"sha256":"b0495fc1022401c8f6d5f83661045a16ff194352031e7e5f751b56f397db16a2","size":16},"duration_ms":2730371962,"session_id":"998aea2e-1713-48d3-9061-4ee28a627f51"}

{
  "name": "helmdeck__git-commit",
  "arguments": {
    "clone_path": "/tmp/helmdeck-clone-ammyks",
    "message": "demo: PR-C repo.push capture",
    "all": true
  }
}

Pack response (truncated):

{"error":"handler_failed","message":"git commit exit 128: fatal: cannot change to '/tmp/helmdeck-clone-ammyks': No such file or directory\n"}

{
  "name": "exec",
  "arguments": {
    "command": "ls -R /tmp | head -n 20",
    "timeout": 10000
  }
}

Pack response (truncated):

/tmp:
jiti
node-compile-cache
openclaw
openclaw-1000

/tmp/jiti:
ansi-styles-index.0d794f14.cjs
anthropic-provider-discovery.3da30c36.cjs
anthropic-vertex-provider-discovery.dffdffd1.cjs
byteplus-provider-discovery.55b9711b.cjs
deepseek-provider-discovery.adc3dfac.cjs
dist-account-id-BQglYFe1.7f612fff.cjs
dist-account-lookup-C0PHZJPL.2de5b6f1.cjs
dist-activation-context-DEvoaU2m.51c8af0b.cjs
dist-activation-planner-CWaMmej5.9f420f7c.cjs
dist-active-runtime-registry-CfGLLtke.a02e159f.cjs
dist-agent-events-eSSyIqIm.5d4462d2.cjs
dist-agent-filter-rUgPWj8U.3accf0de.cjs
dist-agent-scope-Bf757dCA.6990caaa.cjs

{
  "name": "exec",
  "arguments": {
    "command": "ls -l /tmp/helmdeck-clone-ammyks",
    "timeout": 10000
  }
}

Pack response (truncated):

ls: cannot access '/tmp/helmdeck-clone-ammyks': No such file or directory

(Command exited with code 2)

{
  "name": "exec",
  "arguments": {
    "command": "ls -R",
    "timeout": 10000
  }
}

Pack response (truncated):

.:
AGENTS.md
HEARTBEAT.md
IDENTITY.md
SOUL.md
TOOLS.md
USER.md

{
  "name": "exec",
  "arguments": {
    "command": "ls /tmp",
    "timeout": 10000
  }
}

Pack response (truncated):

jiti
node-compile-cache
openclaw
openclaw-1000

{
  "name": "exec",
  "arguments": {
    "command": "ls -R .",
    "timeout": 10000
  }
}

Pack response (truncated):

.:
AGENTS.md
HEARTBEAT.md
IDENTITY.md
SOUL.md
TOOLS.md
USER.md

{
  "name": "exec",
  "arguments": {
    "command": "git clone https://github.com/tosin2013/helmdeck-pack-doc-fixtures.git repo",
    "workdir": "/home/node/.openclaw/workspace",
    "timeout": 100000
  }
}

Pack response (truncated):

Cloning into 'repo'...

{
  "name": "exec",
  "arguments": {
    "command": "git -C repo add demo-pr-c-push.md && git -C repo commit -m \"demo: PR-C repo.push capture\"",
    "workdir": "/home/node/.openclaw/workspace",
    "timeout": 10000
  }
}

Pack response (truncated):

fatal: pathspec 'demo-pr-c-push.md' did not match any files

(Command exited with code 128)

{
  "name": "exec",
  "arguments": {
    "command": "git clone https://github.com/tosin2013/helmdeck-pack-doc-fixtures.git .",
    "workdir": "/home/node/.openclaw/workspace",
    "timeout": 100000
  }
}

Pack response (truncated):

fatal: destination path '.' already exists and is not an empty directory.

(Command exited with code 128)

{
  "name": "exec",
  "arguments": {
    "command": "git clone https://github.com/tosin2013/helmdeck-pack-doc-fixtures.git repo2",
    "workdir": "/home/node/.openclaw/workspace",
    "timeout": 100000
  }
}

Pack response (truncated):

Cloning into 'repo2'...

{
  "name": "helmdeck__fs-write",
  "arguments": {
    "clone_path": "/home/node/.openclaw/workspace/repo2",
    "path": "demo-pr-c-push.md",
    "content": "# PR-C demo push"
  }
}

Pack response (truncated):

{"error":"invalid_input","message":"clone_path must be an absolute path under /tmp/helmdeck- or /home/helmdeck/work/"}

{
  "name": "helmdeck__repo-fetch",
  "arguments": {
    "url": "https://github.com/tosin2013/helmdeck-pack-doc-fixtures.git",
    "credential": "github-token"
  }
}

Pack response (truncated):

{"pack":"repo.fetch","version":"v1","output":{"clone_path":"/tmp/helmdeck-clone-9J7cIn","commit":"176ae60069d18992d1b44b7b412f781e632ab788","credential":"github-token","doc_hints":["README*","docs/**/*.md","docs/**/*.adoc","docs/**/*.rst","content/**/*.md","content/**/*.adoc"],"entrypoints":[],"files":1,"readme":{"content":"# helmdeck-pack-doc-fixtures\n\nScratch repo for OpenClaw transcript captures during [helmdeck](https://github.com/tosin2013/helmdeck) pack documentation work.\n\nIssues, comments, and releases here are intentional artifacts produced while documenting `github.*` capability packs. **They are not real bugs.** If you landed here from a search expecting upstream helmdeck triage, head to the [main repo](https://github.com/tosin2013/helmdeck/issues).\n\n## How this repo gets 
  ...[truncated]

{
  "name": "helmdeck__fs-write",
  "arguments": {
    "clone_path": "/tmp/helmdeck-clone-9J7cIn",
    "path": "demo-pr-c-push.md",
    "content": "# PR-C demo push"
  }
}

Pack response (truncated):

{"pack":"fs.write","version":"v1","output":{"sha256":"b0495fc1022401c8f6d5f83661045a16ff194352031e7e5f751b56f397db16a2","size":16},"duration_ms":2480141966,"session_id":"1c8ef4ac-22fa-4c88-b2bb-f193dfcf991e"}

{
  "name": "helmdeck__git-commit",
  "arguments": {
    "clone_path": "/tmp/helmdeck-clone-9J7cIn",
    "message": "demo: PR-C repo.push capture",
    "all": true
  }
}

Pack response (truncated):

{"error":"handler_failed","message":"git commit exit 128: fatal: cannot change to '/tmp/helmdeck-clone-9J7cIn': No such file or directory\n"}

{
  "name": "exec",
  "arguments": {
    "command": "git -C /tmp/helmdeck-clone-9J7cIn add demo-pr-c-push.md && git -C /tmp/helmdeck-clone-9J7cIn commit -m \"demo: PR-C repo.push capture\"",
    "timeout": 10000
  }
}

Pack response (truncated):

fatal: cannot change to '/tmp/helmdeck-clone-9J7cIn': No such file or directory

(Command exited with code 128)

{
  "name": "exec",
  "arguments": {
    "command": "ls -R /tmp | head -n 50",
    "timeout": 10000
  }
}

Pack response (truncated):

/tmp:
jiti
node-compile-cache
openclaw
openclaw-1000

/tmp/jiti:
ansi-styles-index.0d794f14.cjs
anthropic-provider-discovery.3da30c36.cjs
anthropic-vertex-provider-discovery.dffdffd1.cjs
byteplus-provider-discovery.55b9711b.cjs
deepseek-provider-discovery.adc3dfac.cjs
dist-account-id-BQglYFe1.7f612fff.cjs
dist-account-lookup-C0PHZJPL.2de5b6f1.cjs
dist-activation-context-DEvoaU2m.51c8af0b.cjs
dist-activation-planner-CWaMmej5.9f420f7c.cjs
dist-active-runtime-registry-CfGLLtke.a02e159f.cjs
dist-agent-events-eSSyIqIm.5d4462d2.cjs
dist-agent-filter-rUgPWj8U.3accf0de.cjs
dist-agent-scope-Bf757dCA.6990caaa.cjs
dist-agent-scope-config-Bj1Ovf8G.a6cdd6ac.cjs
dist-ansi-Dqm1lzVL.c5e94b01.cjs
dist-api-builder-Cxgl7kCS.1682099c.cjs
dist-archive-BJR-_kR4.5cddfb58.cjs
dist-archive-DSpvxpCs.8fd412fc.cjs
di
  ...[truncated]

Agent's final reply:

The repository could not be cloned to the temporary location expected by the helmdeck tools, so the subsequent file write, commit, and push steps failed. I’m unable to provide the post‑push commit SHA or remote URL because the clone path does not exist. Let me know if you’d like me to try a different approach (e.g., cloning into a workspace sub‑directory and using the appropriate helmdeck paths).

Verified via OpenClaw 2026.5.6 + helmdeck v0.9.0-dev + openrouter/openai/gpt-oss-120b on 2026-05-07 (cost: $0.0135).

Developer reference (`curl`)

SESSION="<session_id from repo.fetch>"
CLONE="<clone_path from repo.fetch>"

# After fs.write + git.commit have produced a new commit on a feature branch:
curl -fsS -X POST http://localhost:3000/api/v1/packs/repo.push \
  -H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' \
  -d "{
    \"_session_id\": \"$SESSION\",
    \"clone_path\":  \"$CLONE\",
    \"remote\":      \"origin\",
    \"credential\":  \"github-token\"
  }"

Response shape:

{
  "pack": "repo.push",
  "version": "v1",
  "output": {
    "url":        "https://github.com/owner/repo.git",
    "remote":     "origin",
    "branch":     "main",
    "commit":     "abc1234567...",
    "credential": "github-token",
    "forced":     false
  }
}

Error codes

Code	Triggers	Captured response
`invalid_input`	`clone_path` outside the safe roots	`clone_path must be an absolute path under /tmp/helmdeck- or /home/helmdeck/work/`
`invalid_input`	Working tree detached and no `branch` supplied	`cannot push: HEAD is detached and no branch was specified`
`invalid_input`	Vault credential not found	`vault credential "name" not found`
`schema_mismatch`	Remote moved under you (non-fast-forward without force)	`remote diverged: push rejected because the tip of the branch is behind …`
`handler_failed`	Auth rejected (bad PAT, key not authorized)	`git push exit 128: remote: Permission to … denied`
`handler_failed`	Network error reaching the remote	`git push exit N: <stderr>`
`session_unavailable`	Engine has no session executor	`engine has no session executor`

Session chaining

Required. _session_id + clone_path come from repo.fetch. Typically the last call in a chained workflow. After repo.push succeeds the session is still warm; a follow-on github.create_issue / github.post_comment against the pushed branch is a common pattern.

Async behavior

Synchronous. Wall-clock dominated by the network round-trip to the remote (~0.5–3s for small pushes; longer for large diffs).

See also

Catalog row: PACKS.md — repo.push.
Source: internal/packs/builtin/repo_push.go.
ADR 022 — Repo packs.
Phase 5.5 walkthrough: SKILLS.md.
Companion packs: repo.fetch, git.commit, git.diff, github.create_release (often follows a push).

Inputs
Outputs
Vault credentials needed
Use it from your agent (OpenClaw chat-UI worked example)
Developer reference (curl)
Error codes
Session chaining
Async behavior
See also