Skip to content

Agents and the commit API

Read files and write a commit in one API call, with expectedHeadSha so a branch that moved isn't overwritten.

Updated View as Markdown

An agent can work with real git (clone, commit, push with a bot’s key, as in the Quickstart) or through the API without a checkout. The examples use an API key or a bot’s key in $EZGH_API_KEY, and $ORG_ID, $PROJECT_ID and $REPO (gtr_…).

Read

GetContents returns a file at a branch, tag or commit (ref, the default branch when absent), or a folder’s entries. The path is one segment, with / encoded:

curl -H "Authorization: Bearer $EZGH_API_KEY" \
  "https://git-api.ezghcloud.com/v1/organizations/$ORG_ID/projects/$PROJECT_ID/repositories/$REPO/contents/src%2Fheader.tsx?ref=main"

A file’s content is base64, and null past 1 MiB: read those bytes from GetBlob with the file’s sha. GetTree with recursive=true lists every file. GetBranch gives the branch’s head commit.

Write a commit

CreateCommit makes one commit on a branch from a list of write, delete and move changes. expectedHeadSha is the branch’s head you read; the commit is refused if the branch moved since:

curl -X POST -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "branch": "agent/fix-header",
    "startFrom": "main",
    "expectedHeadSha": null,
    "message": "Fix the header on small screens",
    "changes": [
      {"op": "write", "path": "src/header.tsx", "content": "export function Header() {\n  return <header className=\"truncate\">Storefront</header>\n}\n"},
      {"op": "delete", "path": "src/old-header.css"}
    ]
  }' \
  "https://git-api.ezghcloud.com/v1/organizations/$ORG_ID/projects/$PROJECT_ID/repositories/$REPO/commits"
  • A new branch starts from startFrom (a branch, tag or commit; the default branch when absent), and expectedHeadSha is null. An existing branch needs expectedHeadSha.
  • content is text; binary files go as contentBase64. mode 100755 makes a file executable.
  • The answer is 201 with the new commit’s sha. The committer is always you; author sets the author’s name and email.
  • A change set that changes nothing is 400 empty_commit. Branch rules apply as for a push: a protected branch is 409 blocked_by_rule, with the rule’s reason.

When the branch moved

409 conflict means the branch’s head isn’t expectedHeadSha any more: someone else pushed or committed. Read the branch and the files you change again, redo the change on the new head, and send it with the new expectedHeadSha. Use a new Idempotency-Key for the new attempt; repeating the same key replays the first answer.

Then open a pull request

ezgh git prs create site --head agent/fix-header --title "Fix the header on small screens"

See Pull requests. A CI bot or the agent itself reports results on the head commit with ezgh git checks report.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close