repos.commits.create

POST

api

repos

{repo_name}

commit-pack

TypeScript

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

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

const commit = await pierre.repos.commits.create({
  repo_name: 'my-demo-repository',
  author: { email: 'docs@example.com', name: 'Docs Bot' },
  commit_message: 'Update docs',
  expected_target_sha: 'd34db33fd34db33fd34db33fd34db33fd34db33f',
  target_branch: 'main',
  files: [{ path: 'docs/changelog.md', mode: '100644', content: '# Version 2.1.0\n- refresh docs\n' }, { path: 'docs/legacy.txt', operation: 'delete' }],
});
console.log(commit);

from pierre import Pierre

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

commit = pierre.repos.commits.create(
    repo_name="my-demo-repository",
    author={"email": "docs@example.com", "name": "Docs Bot"},
    commit_message="Update docs",
    expected_target_sha="d34db33fd34db33fd34db33fd34db33fd34db33f",
    target_branch="main",
    files=[{"path": "docs/changelog.md", "mode": "100644", "content": "# Version 2.1.0\n- refresh docs\n"}, {"path": "docs/legacy.txt", "operation": "delete"}],
)
print(commit)

import (
	"context"
	"fmt"
	"strings"

	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
}
commit, err := client.Repos.Commits.Create(ctx, pierre.ReposCommitsCreateParams{
	RepoName:          "my-demo-repository",
	Author:            pierre.GitIdentity{Email: "docs@example.com", Name: "Docs Bot"},
	CommitMessage:     "Update docs",
	ExpectedTargetSHA: pierre.String("d34db33fd34db33fd34db33fd34db33fd34db33f"),
	TargetBranch:      "main",
	Files:             []pierre.CommitFile{{Path: "docs/changelog.md", Mode: "100644", Content: strings.NewReader("# Version 2.1.0\n- refresh docs\n")}, {Path: "docs/legacy.txt", Operation: "delete"}},
})
if err != nil {
	return err
}
fmt.Println(commit)

pierre repos:commits create \
  --repo-name my-demo-repository \
  --author.email docs@example.com \
  --author.name 'Docs Bot' \
  --commit-message 'Update docs' \
  --expected-target-sha d34db33fd34db33fd34db33fd34db33fd34db33f \
  --target-branch main \
  --file docs/changelog.md \
  --delete docs/legacy.txt

curl -X POST \
  "https://api.{org}.code.storage/api/repos/my-demo-repository/commit-pack" \
  -H "Authorization: Bearer $PIERRE_TOKEN" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @- <<'EOF'
  {"metadata":{"author":{"email":"docs@example.com","name":"Docs Bot"},"commit_message":"Update docs","expected_target_sha":"d34db33fd34db33fd34db33fd34db33fd34db33f","files":[{"content_id":"blob-1","mode":"100644","operation":"upsert","path":"docs/changelog.md"},{"content_id":"blob-2","operation":"delete","path":"docs/legacy.txt"}],"target_branch":"main"}}
  {"blob_chunk":{"content_id":"blob-1","data":"IyBWZXJzaW9uIDIuMS4wCi0gcmVmcmVzaCBkb2NzCg==","eof":true}}
  {"blob_chunk":{"content_id":"blob-2","data":"","eof":true}}
EOF

{
  "commit": {
    "blob_count": 1,
    "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>"
  }
}

{
  "commit": null,
  "result": {
    "message": "first payload must be metadata",
    "new_sha": "",
    "old_sha": "",
    "status": "invalid",
    "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>"
}

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

{
  "commit": {
    "blob_count": 1,
    "commit_sha": "7b3e9f2a1c4d5e6f708192a3b4c5d6e7f8091a2b",
    "pack_bytes": 1024,
    "target_branch": "main",
    "tree_sha": "e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4"
  },
  "result": {
    "message": "failed to update ref",
    "new_sha": "7b3e9f2a1c4d5e6f708192a3b4c5d6e7f8091a2b",
    "old_sha": "d34db33fd34db33fd34db33fd34db33fd34db33f",
    "status": "failed",
    "success": false,
    "target_branch": "main"
  }
}

{
  "commit": null,
  "result": {
    "message": "no changes to commit",
    "new_sha": "",
    "old_sha": "",
    "status": "precondition_failed",
    "success": false,
    "target_branch": ""
  }
}

{
  "commit": null,
  "result": {
    "message": "commit payload too large: exceeds total blob limit (262144000 bytes)",
    "new_sha": "",
    "old_sha": "",
    "status": "payload_too_large",
    "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.

Path Parameters

repo_name

string

required

The repository name, for example acme/web.

Body

application/x-ndjson

Send newline-delimited JSON where the first line is a metadata object and each following line is a blob_chunk. This lets you stream file contents without a local Git client.

NDJSON stream. The first line must be metadata; subsequent lines must be blob_chunk payloads. Decoded blob chunks are limited to 4 MiB each.

Response

Commit created and written to the target branch.

Result of applying an NDJSON commit pack, including the resulting commit and branch update.

commit

object

required

Commit object information generated by the storage service.

Show child attributes

result

object

required

Final branch update outcome.

Show child attributes

TypeScript

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

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

const commit = await pierre.repos.commits.create({
  repo_name: 'my-demo-repository',
  author: { email: 'docs@example.com', name: 'Docs Bot' },
  commit_message: 'Update docs',
  expected_target_sha: 'd34db33fd34db33fd34db33fd34db33fd34db33f',
  target_branch: 'main',
  files: [{ path: 'docs/changelog.md', mode: '100644', content: '# Version 2.1.0\n- refresh docs\n' }, { path: 'docs/legacy.txt', operation: 'delete' }],
});
console.log(commit);

from pierre import Pierre

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

commit = pierre.repos.commits.create(
    repo_name="my-demo-repository",
    author={"email": "docs@example.com", "name": "Docs Bot"},
    commit_message="Update docs",
    expected_target_sha="d34db33fd34db33fd34db33fd34db33fd34db33f",
    target_branch="main",
    files=[{"path": "docs/changelog.md", "mode": "100644", "content": "# Version 2.1.0\n- refresh docs\n"}, {"path": "docs/legacy.txt", "operation": "delete"}],
)
print(commit)

import (
	"context"
	"fmt"
	"strings"

	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
}
commit, err := client.Repos.Commits.Create(ctx, pierre.ReposCommitsCreateParams{
	RepoName:          "my-demo-repository",
	Author:            pierre.GitIdentity{Email: "docs@example.com", Name: "Docs Bot"},
	CommitMessage:     "Update docs",
	ExpectedTargetSHA: pierre.String("d34db33fd34db33fd34db33fd34db33fd34db33f"),
	TargetBranch:      "main",
	Files:             []pierre.CommitFile{{Path: "docs/changelog.md", Mode: "100644", Content: strings.NewReader("# Version 2.1.0\n- refresh docs\n")}, {Path: "docs/legacy.txt", Operation: "delete"}},
})
if err != nil {
	return err
}
fmt.Println(commit)

pierre repos:commits create \
  --repo-name my-demo-repository \
  --author.email docs@example.com \
  --author.name 'Docs Bot' \
  --commit-message 'Update docs' \
  --expected-target-sha d34db33fd34db33fd34db33fd34db33fd34db33f \
  --target-branch main \
  --file docs/changelog.md \
  --delete docs/legacy.txt

curl -X POST \
  "https://api.{org}.code.storage/api/repos/my-demo-repository/commit-pack" \
  -H "Authorization: Bearer $PIERRE_TOKEN" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @- <<'EOF'
  {"metadata":{"author":{"email":"docs@example.com","name":"Docs Bot"},"commit_message":"Update docs","expected_target_sha":"d34db33fd34db33fd34db33fd34db33fd34db33f","files":[{"content_id":"blob-1","mode":"100644","operation":"upsert","path":"docs/changelog.md"},{"content_id":"blob-2","operation":"delete","path":"docs/legacy.txt"}],"target_branch":"main"}}
  {"blob_chunk":{"content_id":"blob-1","data":"IyBWZXJzaW9uIDIuMS4wCi0gcmVmcmVzaCBkb2NzCg==","eof":true}}
  {"blob_chunk":{"content_id":"blob-2","data":"","eof":true}}
EOF

{
  "commit": {
    "blob_count": 1,
    "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>"
  }
}

{
  "commit": null,
  "result": {
    "message": "first payload must be metadata",
    "new_sha": "",
    "old_sha": "",
    "status": "invalid",
    "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>"
}

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

{
  "commit": {
    "blob_count": 1,
    "commit_sha": "7b3e9f2a1c4d5e6f708192a3b4c5d6e7f8091a2b",
    "pack_bytes": 1024,
    "target_branch": "main",
    "tree_sha": "e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4"
  },
  "result": {
    "message": "failed to update ref",
    "new_sha": "7b3e9f2a1c4d5e6f708192a3b4c5d6e7f8091a2b",
    "old_sha": "d34db33fd34db33fd34db33fd34db33fd34db33f",
    "status": "failed",
    "success": false,
    "target_branch": "main"
  }
}

{
  "commit": null,
  "result": {
    "message": "no changes to commit",
    "new_sha": "",
    "old_sha": "",
    "status": "precondition_failed",
    "success": false,
    "target_branch": ""
  }
}

{
  "commit": null,
  "result": {
    "message": "commit payload too large: exceeds total blob limit (262144000 bytes)",
    "new_sha": "",
    "old_sha": "",
    "status": "payload_too_large",
    "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

Authorizations

Path Parameters

Body

Response