Skip to main content
POST
/
api
/
repos
/
{repo_name}
/
merge
Merge Branch
curl --request POST \
  --url https://api.{cluster}.code.storage/api/repos/{repo_name}/merge \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "commit_message": "Merge feature/preview",
  "expected_target_sha": "c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2",
  "source_branch": "feature/preview",
  "source_is_ephemeral": true,
  "squash": false,
  "strategy": "merge",
  "target_branch": "main"
}
'
{
  "commit_sha": "41f0d5c6cc5f4d0fb4a3af2de27ccf9a80ab3b84",
  "merge_base_sha": "a2d127e6a4d54bb7390de828a99e36411f0c84df",
  "promoted_commits": 3,
  "result": "merged",
  "source": {
    "branch": "feature/preview",
    "ephemeral": true,
    "sha": "9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1"
  },
  "target": {
    "branch": "main",
    "new_sha": "41f0d5c6cc5f4d0fb4a3af2de27ccf9a80ab3b84",
    "old_sha": "c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2"
  },
  "tree_sha": "b9532c5d5be50d88e2f45d7c229566b2f1f99731"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
repo_name
string
required

Repository name. Names that contain / or any other character that is not safe in a URL path segment must be URL encoded so the value occupies a single path segment. For example pierre/example is sent as pierre%2Fexample. Plain names such as example can be sent as-is. The server URL-decodes the value before resolving the repository.

Body

application/json

Merge a source branch into a target branch using a merge commit, fast-forward only, or fast-forward preferred behaviour. Source and target can live in the default or ephemeral namespace. When expected_target_sha is omitted, the gateway may retry stale target updates internally while keeping the originally resolved source commit pinned. Automatic stale-target retry is disabled for GitHub-backed public targets.

Merge request body specifying source and target branches, optional pinned source SHA, merge strategy, optional squash flag, and optional retry-on-target-move behavior, which is currently unsupported for GitHub-backed public targets.

​
source_branch
string
required

Source branch to merge from.

Example:

"feature/preview"

​
strategy
enum<string>
required

Merge strategy. merge creates a merge commit when needed, ff_only rejects non-fast-forward merges, and ff_prefer fast-forwards when possible before falling back to a merge commit.

Available options:
merge,
ff_only,
ff_prefer
Example:

"merge"

​
target_branch
string
required

Destination branch to update.

Example:

"main"

​
allow_unrelated_histories
boolean

Permit merges between unrelated histories.

​
author
object

Author identity used when the backend creates a merge commit. Required for merge-commit strategies.

​
commit_message
string

Commit message used when a merge commit is created.

Example:

"Merge feature/preview"

​
committer
object

Committer identity for the merge commit. Defaults to author when omitted.

​
expected_target_sha
string

Optional branch tip guard. The merge fails if the target has moved since this SHA.

Example:

"c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2"

​
source_is_ephemeral
boolean

Whether source_branch should be resolved from the ephemeral namespace.

Example:

true

​
squash
boolean

When true, collapse the source into a single new commit whose only parent is the current target tip. Defaults to false, which preserves the standard merge/fast-forward behavior. Incompatible with the ff_only strategy.

Example:

false

​
target_is_ephemeral
boolean

Whether target_branch should be resolved from the ephemeral namespace.

Response

Merge result, including the source and target commit state after the operation.

Merge outcome including the resulting commit, source and target state, merge base information, and retry attempt counters when applicable.

​
commit_sha
string
required

Commit SHA for the merge result. For a fast-forward or no-op, this is the resulting target tip.

Example:

"41f0d5c6cc5f4d0fb4a3af2de27ccf9a80ab3b84"

​
promoted_commits
integer<int32>
required

Number of commits promoted from source onto target.

Required range: x >= 0
Example:

3

​
result
string
required

Merge outcome: merge_commit, fast_forward, no_op, squash, or unknown.

Example:

"merged"

​
source
object
required

Source ref metadata with branch, ephemeral, and resolved sha.

​
target
object
required

Target ref metadata with branch, ephemeral, previous old_sha, and resulting new_sha.

​
tree_sha
string
required

Tree SHA for the resulting commit or target tip.

Example:

"b9532c5d5be50d88e2f45d7c229566b2f1f99731"

​
merge_base_sha
string

Merge base SHA when one exists and the backend reports it.

Example:

"a2d127e6a4d54bb7390de828a99e36411f0c84df"