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.

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,
  "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,
    "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.

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.

Merge request body specifying source and target branches, merge strategy, optional squash flag, and optional author or committer for a merge commit.

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.

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_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

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, and merge base information.

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"