repos.merge

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. Set expected_source_sha to merge the exact source commit that a preview returned, even if the source branch advances. 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.

Scope: git:write on the repository.

POST

api

repos

{repo_name}

merge

TypeScript

import { Pierre } from '@pierre/sdk';

// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
const pierre = new Pierre();

const result = await pierre.repos.merge({
  repo_name: 'my-demo-repository',
  author: { email: 'review@example.com', name: 'Review Bot' },
  commit_message: 'Merge feature/preview',
  committer: { email: 'review@example.com', name: 'Review Bot' },
  expected_source_sha: '9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1',
  expected_target_sha: 'c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2',
  source_is_ephemeral: true,
  source_ref: 'feature/preview',
  strategy: 'merge',
  target_branch: 'main',
});
console.log(result);

from pierre import Pierre

# The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
pierre = Pierre()

result = pierre.repos.merge(
    repo_name="my-demo-repository",
    author={"email": "review@example.com", "name": "Review Bot"},
    commit_message="Merge feature/preview",
    committer={"email": "review@example.com", "name": "Review Bot"},
    expected_source_sha="9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1",
    expected_target_sha="c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2",
    source_is_ephemeral=True,
    source_ref="feature/preview",
    strategy="merge",
    target_branch="main",
)
print(result)

import (
	"context"
	"fmt"

	pierre "github.com/pierrecomputer/sdk/go"
)

ctx := context.Background()
// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
client, err := pierre.NewClient()
if err != nil {
	return err
}
result, err := client.Repos.Merge(ctx, pierre.ReposMergeParams{
	RepoName:          "my-demo-repository",
	Author:            pierre.Value(pierre.GitIdentity{Email: "review@example.com", Name: "Review Bot"}),
	CommitMessage:     pierre.String("Merge feature/preview"),
	Committer:         pierre.Value(pierre.GitIdentity{Email: "review@example.com", Name: "Review Bot"}),
	ExpectedSourceSHA: pierre.String("9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1"),
	ExpectedTargetSHA: pierre.String("c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2"),
	SourceIsEphemeral: pierre.Bool(true),
	SourceRef:         pierre.String("feature/preview"),
	Strategy:          pierre.ReposMergeRequestStrategy("merge"),
	TargetBranch:      "main",
})
if err != nil {
	return err
}
fmt.Println(result)

pierre repos merge \
  --repo-name my-demo-repository \
  --author.email review@example.com \
  --author.name 'Review Bot' \
  --commit-message 'Merge feature/preview' \
  --committer.email review@example.com \
  --committer.name 'Review Bot' \
  --expected-source-sha 9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1 \
  --expected-target-sha c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 \
  --source-is-ephemeral \
  --source-ref feature/preview \
  --strategy merge \
  --target-branch main

curl -X POST \
  "https://api.{org}.code.storage/api/repos/my-demo-repository/merge" \
  -H "Authorization: Bearer $PIERRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "author": {
      "email": "review@example.com",
      "name": "Review Bot"
    },
    "commit_message": "Merge feature/preview",
    "committer": {
      "email": "review@example.com",
      "name": "Review Bot"
    },
    "expected_source_sha": "9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1",
    "expected_target_sha": "c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2",
    "source_is_ephemeral": true,
    "source_ref": "feature/preview",
    "strategy": "merge",
    "target_branch": "main"
  }'

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

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>",
  "invalid_params": [
    {
      "name": "deployment.production_branch",
      "reason": "exceeds 255 characters"
    }
  ]
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "conflict_type": "merge_conflict",
  "error": "merge conflict"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

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.

Scopes

git:write

Path Parameters

repo_name

string

required

The repository name, for example acme/web.

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. Set expected_source_sha to merge the source commit that a preview returned: the merge uses that commit, and fails if source_ref no longer contains it. 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 makes a merge commit, also when a fast-forward is possible. ff_prefer fast-forwards when it can, and else makes a merge commit. ff_only only fast-forwards and never makes a commit. It fails with 412 when the target has commits that the source does not have. When the target already contains the source, each strategy returns no_op and makes no 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 of the commit that the merge makes. Required when the merge makes a commit: with merge, with ff_prefer when a fast-forward is not possible, and with squash.

Show child attributes

commit_message

string

Message of the commit that the merge makes. Required with squash. When it is omitted, a merge commit gets a message in the form Merge branch 'feature' into main, with the source and target branch names of the request.

Example:

"Merge feature/preview"

committer

object

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

Show child attributes

expected_source_sha

string

Optional source commit guard. The merge uses this commit instead of the current tip of source_ref, and fails if source_ref does not contain it when the merge starts. A later advance of source_ref does not change the merged commit.

Example:

"9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1"

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, makes one new commit with the current target tip as its only parent, also when a fast-forward is possible. Defaults to false. 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:

"merge_commit"

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"

TypeScript

import { Pierre } from '@pierre/sdk';

// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
const pierre = new Pierre();

const result = await pierre.repos.merge({
  repo_name: 'my-demo-repository',
  author: { email: 'review@example.com', name: 'Review Bot' },
  commit_message: 'Merge feature/preview',
  committer: { email: 'review@example.com', name: 'Review Bot' },
  expected_source_sha: '9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1',
  expected_target_sha: 'c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2',
  source_is_ephemeral: true,
  source_ref: 'feature/preview',
  strategy: 'merge',
  target_branch: 'main',
});
console.log(result);

from pierre import Pierre

# The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
pierre = Pierre()

result = pierre.repos.merge(
    repo_name="my-demo-repository",
    author={"email": "review@example.com", "name": "Review Bot"},
    commit_message="Merge feature/preview",
    committer={"email": "review@example.com", "name": "Review Bot"},
    expected_source_sha="9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1",
    expected_target_sha="c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2",
    source_is_ephemeral=True,
    source_ref="feature/preview",
    strategy="merge",
    target_branch="main",
)
print(result)

import (
	"context"
	"fmt"

	pierre "github.com/pierrecomputer/sdk/go"
)

ctx := context.Background()
// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
client, err := pierre.NewClient()
if err != nil {
	return err
}
result, err := client.Repos.Merge(ctx, pierre.ReposMergeParams{
	RepoName:          "my-demo-repository",
	Author:            pierre.Value(pierre.GitIdentity{Email: "review@example.com", Name: "Review Bot"}),
	CommitMessage:     pierre.String("Merge feature/preview"),
	Committer:         pierre.Value(pierre.GitIdentity{Email: "review@example.com", Name: "Review Bot"}),
	ExpectedSourceSHA: pierre.String("9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1"),
	ExpectedTargetSHA: pierre.String("c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2"),
	SourceIsEphemeral: pierre.Bool(true),
	SourceRef:         pierre.String("feature/preview"),
	Strategy:          pierre.ReposMergeRequestStrategy("merge"),
	TargetBranch:      "main",
})
if err != nil {
	return err
}
fmt.Println(result)

pierre repos merge \
  --repo-name my-demo-repository \
  --author.email review@example.com \
  --author.name 'Review Bot' \
  --commit-message 'Merge feature/preview' \
  --committer.email review@example.com \
  --committer.name 'Review Bot' \
  --expected-source-sha 9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1 \
  --expected-target-sha c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2 \
  --source-is-ephemeral \
  --source-ref feature/preview \
  --strategy merge \
  --target-branch main

curl -X POST \
  "https://api.{org}.code.storage/api/repos/my-demo-repository/merge" \
  -H "Authorization: Bearer $PIERRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "author": {
      "email": "review@example.com",
      "name": "Review Bot"
    },
    "commit_message": "Merge feature/preview",
    "committer": {
      "email": "review@example.com",
      "name": "Review Bot"
    },
    "expected_source_sha": "9eb378bdb5bf1944f6ba0bd5a2c4df3ce32f4df1",
    "expected_target_sha": "c4f0fdfc41adab56630b34f5f4fd4e84a2c5b4d2",
    "source_is_ephemeral": true,
    "source_ref": "feature/preview",
    "strategy": "merge",
    "target_branch": "main"
  }'

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

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>",
  "invalid_params": [
    {
      "name": "deployment.production_branch",
      "reason": "exceeds 255 characters"
    }
  ]
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "conflict_type": "merge_conflict",
  "error": "merge conflict"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

Getting Started

Platform

Workflows

Libraries

API Reference

repos.merge

Authorizations

Scopes

Path Parameters

Body

Response