repos.commits.restore

Create a new commit that resets a branch back to a specific commit SHA while preserving normal Git history.

Ref-level outcomes are reported in result.status and result.success, not by the status code alone, and failures raised by the restore itself come back in that same restore-result body. The problem-details schemas below describe gateway-level rejections such as 401, 403 and 429.

Scope: git:write on the repository.

POST

api

repos

{repo_name}

restore-commit

TypeScript

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

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

const result = await pierre.repos.commits.restore({
  repo_name: 'my-demo-repository',
  author: { email: 'docs@example.com', name: 'Docs Bot' },
  base_ref: 'abc123def4567890abc123def4567890abc123de',
  commit_message: 'Reset branch',
  expected_target_sha: '0123456789abcdef0123456789abcdef01234567',
  target_branch: 'main',
});
console.log(result);

from pierre import Pierre

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

result = pierre.repos.commits.restore(
    repo_name="my-demo-repository",
    author={"email": "docs@example.com", "name": "Docs Bot"},
    base_ref="abc123def4567890abc123def4567890abc123de",
    commit_message="Reset branch",
    expected_target_sha="0123456789abcdef0123456789abcdef01234567",
    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.Commits.Restore(ctx, pierre.ReposCommitsRestoreParams{
	RepoName:          "my-demo-repository",
	Author:            pierre.GitIdentity{Email: "docs@example.com", Name: "Docs Bot"},
	BaseRef:           pierre.String("abc123def4567890abc123def4567890abc123de"),
	CommitMessage:     pierre.String("Reset branch"),
	ExpectedTargetSHA: pierre.String("0123456789abcdef0123456789abcdef01234567"),
	TargetBranch:      "main",
})
if err != nil {
	return err
}
fmt.Println(result)

pierre repos:commits restore \
  --repo-name my-demo-repository \
  --author.email docs@example.com \
  --author.name 'Docs Bot' \
  --base-ref abc123def4567890abc123def4567890abc123de \
  --commit-message 'Reset branch' \
  --expected-target-sha 0123456789abcdef0123456789abcdef01234567 \
  --target-branch main

curl -X POST \
  "https://api.{org}.code.storage/api/repos/my-demo-repository/restore-commit" \
  -H "Authorization: Bearer $PIERRE_TOKEN" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @- <<'EOF'
  {"metadata":{"author":{"email":"docs@example.com","name":"Docs Bot"},"base_ref":"abc123def4567890abc123def4567890abc123de","commit_message":"Reset branch","expected_target_sha":"0123456789abcdef0123456789abcdef01234567","target_branch":"main"}}
EOF

{
  "commit": {
    "commit_sha": "<string>",
    "pack_bytes": 1,
    "target_branch": "<string>",
    "tree_sha": "<string>"
  },
  "result": {
    "branch": "<string>",
    "new_sha": "<string>",
    "old_sha": "<string>",
    "status": "ok",
    "success": true,
    "target_branch": "<string>",
    "message": "<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>"
}

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

{
  "commit": null,
  "result": {
    "message": "branch already matches target commit",
    "new_sha": "",
    "old_sha": "",
    "status": "precondition_failed",
    "success": false,
    "target_branch": ""
  }
}

{
  "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>"
}

{
  "commit": null,
  "result": {
    "message": "upstream Git server request failed; the push may or may not have been applied, check the branch before retrying",
    "new_sha": "",
    "old_sha": "",
    "status": "internal",
    "success": false,
    "target_branch": ""
  }
}

{
  "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/x-ndjson

Send a single NDJSON metadata line describing the branch to restore and the commit SHA to restore it to.

NDJSON stream containing one metadata object.

metadata

object

required

The only line.

Show child attributes

Response

Restore commit created successfully.

Result of a restore commit operation, including the created commit and the branch update.

commit

object

required

Created restore commit metadata.

Show child attributes

result

object

required

Branch update result.

Show child attributes

TypeScript

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

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

const result = await pierre.repos.commits.restore({
  repo_name: 'my-demo-repository',
  author: { email: 'docs@example.com', name: 'Docs Bot' },
  base_ref: 'abc123def4567890abc123def4567890abc123de',
  commit_message: 'Reset branch',
  expected_target_sha: '0123456789abcdef0123456789abcdef01234567',
  target_branch: 'main',
});
console.log(result);

from pierre import Pierre

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

result = pierre.repos.commits.restore(
    repo_name="my-demo-repository",
    author={"email": "docs@example.com", "name": "Docs Bot"},
    base_ref="abc123def4567890abc123def4567890abc123de",
    commit_message="Reset branch",
    expected_target_sha="0123456789abcdef0123456789abcdef01234567",
    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.Commits.Restore(ctx, pierre.ReposCommitsRestoreParams{
	RepoName:          "my-demo-repository",
	Author:            pierre.GitIdentity{Email: "docs@example.com", Name: "Docs Bot"},
	BaseRef:           pierre.String("abc123def4567890abc123def4567890abc123de"),
	CommitMessage:     pierre.String("Reset branch"),
	ExpectedTargetSHA: pierre.String("0123456789abcdef0123456789abcdef01234567"),
	TargetBranch:      "main",
})
if err != nil {
	return err
}
fmt.Println(result)

pierre repos:commits restore \
  --repo-name my-demo-repository \
  --author.email docs@example.com \
  --author.name 'Docs Bot' \
  --base-ref abc123def4567890abc123def4567890abc123de \
  --commit-message 'Reset branch' \
  --expected-target-sha 0123456789abcdef0123456789abcdef01234567 \
  --target-branch main

curl -X POST \
  "https://api.{org}.code.storage/api/repos/my-demo-repository/restore-commit" \
  -H "Authorization: Bearer $PIERRE_TOKEN" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @- <<'EOF'
  {"metadata":{"author":{"email":"docs@example.com","name":"Docs Bot"},"base_ref":"abc123def4567890abc123def4567890abc123de","commit_message":"Reset branch","expected_target_sha":"0123456789abcdef0123456789abcdef01234567","target_branch":"main"}}
EOF

{
  "commit": {
    "commit_sha": "<string>",
    "pack_bytes": 1,
    "target_branch": "<string>",
    "tree_sha": "<string>"
  },
  "result": {
    "branch": "<string>",
    "new_sha": "<string>",
    "old_sha": "<string>",
    "status": "ok",
    "success": true,
    "target_branch": "<string>",
    "message": "<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>"
}

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

{
  "commit": null,
  "result": {
    "message": "branch already matches target commit",
    "new_sha": "",
    "old_sha": "",
    "status": "precondition_failed",
    "success": false,
    "target_branch": ""
  }
}

{
  "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>"
}

{
  "commit": null,
  "result": {
    "message": "upstream Git server request failed; the push may or may not have been applied, check the branch before retrying",
    "new_sha": "",
    "old_sha": "",
    "status": "internal",
    "success": false,
    "target_branch": ""
  }
}

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

Getting Started

Platform

Workflows

Libraries

API Reference

repos.commits.restore

Authorizations

Scopes

Path Parameters

Body

Response