Merge Branch

Merge changes between branches without cloning the repository or shelling out to Git. This endpoint also supports promoting work from ephemeral branches into long-lived branches such as main. Omit expected_target_sha to merge into the current target tip and allow the gateway to retry stale target/repository movement internally; set expected_target_sha to require a strict target-tip precondition. GitHub-backed public targets currently do not use automatic retry.

JWT claims

Required scopes: git:write
Requires per repo scope: Yes

Deprecated: Use /api/repos/{repo_name}/merge instead.

POST /api/v1/repos/merge

Merge Branch

cURL

curl --request POST \
  --url https://api.{cluster}.code.storage/api/v1/repos/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,
  "source_ref": "feature/preview",
  "squash": false,
  "strategy": "merge",
  "target_branch": "main"
}
'

200

{
  "commit_sha": "41f0d5c6cc5f4d0fb4a3af2de27ccf9a80ab3b84",
  "merge_base_sha": "a2d127e6a4d54bb7390de828a99e36411f0c84df",
  "promoted_commits": 3,
  "result": "merged",
  "source": {
    "branch": "feature/preview",
    "ephemeral": true,
    "ref": "feature/preview",
    "sha": "9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1"
  },
  "target": {
    "branch": "main",
    "new_sha": "41f0d5c6cc5f4d0fb4a3af2de27ccf9a80ab3b84",
    "old_sha": "c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2"
  },
  "tree_sha": "b9532c5d5be50d88e2f45d7c229566b2f1f99731"
}

Authorizations

Authorization · string · header · required

JWT bearer token signed with your organization's registered signing key. There is no OAuth authorization server; you mint tokens yourself and the token's scopes claim carries the granted permission scopes. Public scopes: git:read (read repository contents), git:write (write branches, commits, tags, and notes), repo:write (create and manage repositories), org:read (list an organization's repositories). Each operation's security requirement names the scopes it requires. See https://code.storage/docs/getting-started/authentication for how to mint tokens.

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.

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. A merge always updates a branch.

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.

Show child attributes

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.

Show child attributes

expected_target_sha · string

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

Example:

"c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2"

source_branch · string · deprecated

Deprecated: use source_ref. Source branch to merge from.

Example:

"feature/preview"

source_is_ephemeral · boolean

Whether source_ref should be resolved from the ephemeral namespace.

Example:

true

source_ref · string

Branch or refs/heads ref to merge from. The merge reads the source and never updates it. Provide source_ref or the deprecated source_branch.

Example:

"feature/preview"

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

200

application/json

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.

Show child attributes

target · object · required

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

Show child attributes

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"