Skip to main content

Documentation Index

Fetch the complete documentation index at: https://code.storage/docs/llms.txt

Use this file to discover all available pages before exploring further.

Merge one branch into another using merge, ff_only, or ff_prefer. 
POST /api/v1/repos/merge
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "source_branch": "feature/preview",
  "source_is_ephemeral": true,
  "target_branch": "main",
  "target_is_ephemeral": false,
  "expected_target_sha": "0123456789abcdef0123456789abcdef01234567",
  "strategy": "merge",
  "commit_message": "Merge feature/preview",
  "author": {
    "name": "Merge Bot",
    "email": "merge@example.com"
  },
  "committer": {
    "name": "Merge Bot",
    "email": "merge@example.com"
  },
  "allow_unrelated_histories": false
}

​
Request Body

​
source_branch
string
required
Source branch name. Pass a plain branch name, not a full refs/... path.
​
source_is_ephemeral
boolean
When true, resolves source_branch under refs/namespaces/ephemeral/refs/heads/<source_branch>.
​
target_branch
string
required
Target branch name. Pass a plain branch name, not a full refs/... path.
​
target_is_ephemeral
boolean
When true, resolves target_branch under refs/namespaces/ephemeral/refs/heads/<target_branch>.
​
strategy
string
required
Merge strategy. Must be one of merge, ff_only, or ff_prefer.
​
expected_target_sha
string
Optional optimistic concurrency guard. The merge is rejected if the current target tip does not match this SHA.
​
commit_message
string
Commit message for merge-commit results. Required when the backend needs to create a merge commit.
​
author
object
Commit author object with name and email. Required when the backend needs to create a merge commit.
​
committer
object
Optional committer object with name and email. Defaults to author when omitted.
​
allow_unrelated_histories
boolean
When true, allows merging branches with no common ancestor.

​
JWT Requirements

  • The JWT must include the repository in the repo claim
  • Requires git:write scope

​
Response

{
  "result": "merge_commit",
  "commit_sha": "89abcdef0123456789abcdef0123456789abcdef",
  "tree_sha": "fedcba9876543210fedcba9876543210fedcba98",
  "source": {
    "branch": "feature/preview",
    "ephemeral": true,
    "sha": "1234567890abcdef1234567890abcdef12345678"
  },
  "target": {
    "branch": "main",
    "ephemeral": false,
    "old_sha": "0123456789abcdef0123456789abcdef01234567",
    "new_sha": "89abcdef0123456789abcdef0123456789abcdef"
  },
  "merge_base_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "promoted_commits": 2
}

​
Response Fields

​
result
string
Merge outcome: merge_commit, fast_forward, no_op, or unknown.
​
commit_sha
string
Commit SHA for the merge result. For a fast-forward or no-op, this is the resulting target tip.
​
tree_sha
string
Tree SHA for the resulting commit or target tip.
​
source
object
Source ref metadata with branch, ephemeral, and resolved sha.
​
target
object
Target ref metadata with branch, ephemeral, previous old_sha, and resulting new_sha.
​
merge_base_sha
string
Merge base SHA when one exists and the backend reports it.
​
promoted_commits
number
Number of commits promoted from source onto target.

​
Conflict Response

When the merge has conflicts, the API returns 409 Conflict with the conflicting paths and merge base: 
{
  "error": "merge conflict",
  "conflict_paths": ["docs/conflict.txt"],
  "merge_base_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

​
Notes

  • source_branch and target_branch are branch names, not arbitrary refs.
  • The ephemeral flags are namespace selectors. They tell the backend to resolve the branch under the ephemeral namespace before merging.
  • ff_only rejects non-fast-forward merges.
  • ff_prefer fast-forwards when possible and falls back to a merge commit when necessary.
  • commit_message and author are only required when the backend creates a merge commit. They are not required for a pure fast-forward or no_op result.
  • On connected GitHub-backed repositories, ephemeral-to-default merges are handled as third-party-safe promotions so the returned pack includes source ancestry when needed.

​
Error Responses

​
400 Bad Request
string
Invalid request body, invalid strategy, invalid branch name, or source and target resolving to the same branch.
​
401 Unauthorized
string
Invalid JWT or missing authorization header.
​
403 Forbidden
string
Missing git:write scope.
​
404 Not Found
string
Repository or branch not found.
​
409 Conflict
string
Merge conflict or expected target SHA mismatch.
​
412 Precondition Failed
string
Non-fast-forward merge rejected by ff_only, or unrelated histories rejected without allow_unrelated_histories.
​
413 Payload Too Large
string
The generated merge pack exceeded backend size limits.
​
502 Bad Gateway
string
Storage returned an invalid merge-pack stream.
​
503 Service Unavailable
string
Storage coordination or repository runtime was unavailable.