---
source_keys:
  - gitea-mcp-repo
  - gitea-mcp-slim-go
---

# Canonical call sequences

## Push a file to a new branch, then open a PR

```
1. get_repository_tree or get_file_contents on the base branch — only needed if the
   new file is actually replacing an existing one; skip for a brand-new path.

2. create_or_update_file
     owner, repo
     path: "docs/example.md"
     content: "<base64-encoded content>"
     message: "docs: add example"
     branch_name: "main"
     new_branch_name: "feat/add-example"   ← branches off before the commit lands
     (sha omitted — this is a new file)

3. Hand off to gitea-prs to open a PR from "feat/add-example" into "main".
```

`new_branch_name` on `create_or_update_file` replaces a separate branch-creation call — the branch is created and the commit lands on it in one step.

## Update a file when you don't already have its SHA

SHA is mandatory for updates. If it wasn't captured earlier in the conversation:

```
1. get_file_contents
     owner, repo
     ref: "main"
     path: "docs/example.md"
   → read the top-level `sha` field (not content.sha)

2. create_or_update_file
     owner, repo
     path: "docs/example.md"
     content: "<new base64-encoded content>"
     message: "docs: update example"
     branch_name: "main"
     sha: "<sha from step 1>"
```

Do not guess or omit the SHA — the write either fails (409 on create-path fallback) or is rejected outright.

## Delete a file

Same SHA-first pattern, no fallback path:

```
1. get_file_contents  owner, repo, ref: "main", path: "docs/old-example.md"
   → read the top-level `sha` field

2. delete_file
     owner, repo
     path: "docs/old-example.md"
     message: "docs: remove old example"
     branch_name: "main"
     sha: "<sha from step 1>"
```