> ## 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 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. ## OpenAPI ````yaml https://api.pierre.code.storage/api/openapi.json post /api/v1/repos/merge openapi: 3.1.0 info: description: >- The Code Storage HTTP API exposes repository management, Git reads, and write workflows over plain HTTPS. ## Authentication Send a signed JWT in the `Authorization: Bearer ` header on every request. - Organisation-scoped endpoints such as `GET /api/repos` require organisation scopes like `org:read` - Repository-scoped endpoints require a JWT whose `repo` claim names the target repository - Write operations require the relevant scope such as `git:write` or `repo:write` ## Pagination List endpoints use cursor-based pagination. - `cursor` is an opaque token returned by the previous response - `limit` defaults to `20` and is capped per endpoint - `has_more` tells you whether another request is available - `next_cursor` becomes the next `cursor` value ## Paths Preferred routes use the shorter `/api/...` form. Legacy `/api/v1/...` aliases remain documented where they are still supported and are marked as deprecated when a preferred route exists. ## Repository names in paths - Names containing `/` (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` becomes `pierre%2Fexample` and the request URL is `/api/repos/pierre%2Fexample/...`. - Plain names that contain only URL-safe characters can be sent as-is: `/api/repos/dotfiles/...`. - The server URL-decodes the value before resolving the repository, so double-encoding is not required. ## Errors Most endpoints return RFC 9457-compatible problem details under `application/problem+json`, with a legacy `error` field mirrored from `detail`. Streaming commit and note workflows may return operation-specific failure bodies so callers can inspect partial results, branch state, or workflow status without parsing generic error strings. title: code.storage version: 1.0.0 servers: - description: Code Storage tenant cluster url: https://api.{cluster}.code.storage variables: cluster: default: cluster description: >- Tenant cluster identifier (e.g. pierre-dev, pierre-staging, pierre-prod). security: [] tags: - description: Create, inspect, update, delete, and synchronise repositories. name: Repositories - description: Create, delete, list, and compare branches. name: Branches - description: >- Read commit metadata and diffs, or create commits without a local Git client. name: Commits - description: >- Read repository trees, file contents, archives, and server-side search results. name: Files - description: List, create, and delete Git tags. name: Tags - description: Attach and retrieve Git notes for commits or other Git objects. name: Notes - description: >- Trigger upstream synchronisation for repositories backed by an external source. name: Sync - description: Manage generic HTTPS Git credentials for non-GitHub upstreams. name: Credentials paths: /api/v1/repos/merge: post: tags: - Branches summary: Merge Branch description: >- 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. operationId: merge_branch_legacy requestBody: content: application/json: example: commit_message: Merge feature/preview expected_target_sha: c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 source_branch: feature/preview source_is_ephemeral: true squash: false strategy: merge target_branch: main schema: additionalProperties: false description: >- 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. properties: allow_unrelated_histories: description: Permit merges between unrelated histories. type: boolean author: additionalProperties: false description: >- Author identity used when the backend creates a merge commit. Required for merge-commit strategies. properties: email: description: Email address for the signature. type: string name: description: Display name for the signature. type: string required: - name - email type: object commit_message: description: Commit message used when a merge commit is created. examples: - Merge feature/preview type: string committer: additionalProperties: false description: >- Committer identity for the merge commit. Defaults to author when omitted. properties: email: description: Email address for the signature. type: string name: description: Display name for the signature. type: string required: - name - email type: object expected_target_sha: description: >- Optional branch tip guard. The merge fails if the target has moved since this SHA. examples: - c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 type: string source_branch: description: Source branch to merge from. examples: - feature/preview type: string source_is_ephemeral: description: >- Whether source_branch should be resolved from the ephemeral namespace. examples: - true type: boolean squash: description: >- 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. examples: - false type: boolean strategy: description: >- 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. enum: - merge - ff_only - ff_prefer examples: - merge type: string target_branch: description: Destination branch to update. examples: - main type: string target_is_ephemeral: description: >- Whether target_branch should be resolved from the ephemeral namespace. type: boolean required: - source_branch - target_branch - strategy type: object description: >- 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. required: true responses: '200': content: application/json: example: 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 schema: additionalProperties: false description: >- Merge outcome including the resulting commit, source and target state, merge base information, and retry attempt counters when applicable. properties: commit_sha: description: >- Commit SHA for the merge result. For a fast-forward or no-op, this is the resulting target tip. examples: - 41f0d5c6cc5f4d0fb4a3af2de27ccf9a80ab3b84 type: string merge_base_sha: description: Merge base SHA when one exists and the backend reports it. examples: - a2d127e6a4d54bb7390de828a99e36411f0c84df type: string promoted_commits: description: Number of commits promoted from source onto target. examples: - 3 format: int32 minimum: 0 type: integer result: description: >- Merge outcome: merge_commit, fast_forward, no_op, squash, or unknown. examples: - merged type: string source: additionalProperties: false description: >- Source ref metadata with branch, ephemeral, and resolved sha. properties: branch: description: Source branch name. examples: - feature/preview type: string ephemeral: description: >- Whether the source ref was resolved under the ephemeral namespace. examples: - true type: boolean sha: description: Resolved source SHA. examples: - 9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1 type: string required: - branch - ephemeral - sha type: object target: additionalProperties: false description: >- Target ref metadata with branch, ephemeral, previous old_sha, and resulting new_sha. properties: branch: description: Target branch name. examples: - main type: string ephemeral: description: >- Whether the target ref was resolved under the ephemeral namespace. type: boolean new_sha: description: New target tip SHA after the merge. examples: - 41f0d5c6cc5f4d0fb4a3af2de27ccf9a80ab3b84 type: string old_sha: description: Previous target tip SHA before the merge. examples: - c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 type: string required: - branch - ephemeral - old_sha - new_sha type: object tree_sha: description: Tree SHA for the resulting commit or target tip. examples: - b9532c5d5be50d88e2f45d7c229566b2f1f99731 type: string required: - result - commit_sha - tree_sha - source - target - promoted_commits type: object description: >- Merge result, including the source and target commit state after the operation. '400': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object description: Bad Request '401': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object description: Unauthorized '403': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object description: Forbidden '404': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object description: Not Found '409': content: application/json: example: conflict_type: merge_conflict error: merge conflict schema: additionalProperties: false properties: conflict_paths: description: Repository paths that conflicted during the merge. items: type: string type: array conflict_type: description: >- Machine-readable conflict type: merge_conflict, target_moved, or repo_changed. examples: - merge_conflict type: string error: description: High-level conflict result. examples: - merge conflict type: string merge_base_sha: description: Merge base SHA used when the conflict was calculated. type: string required: - error type: object description: >- The merge could not be completed because of file-level conflicts, or an automatic stale-target retry could not absorb concurrent target/repository movement. Inspect conflict_type to distinguish merge_conflict, target_moved, and repo_changed. '429': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object description: Too Many Requests '500': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object description: Internal Server Error '503': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object description: Service Unavailable deprecated: true security: - bearerAuth: [] components: securitySchemes: bearerAuth: bearerFormat: JWT scheme: bearer type: http ````