> ## 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.

# repo.createNote()

> Create a new note on a commit. Fails if a note already exists.

> [!WARNING]
>
> This page documents the earlier Code Storage SDKs: `@pierre/storage`, `pierre-storage`, and
> `code-storage-go`. New code uses the [Pierre SDK](https://code.storage/docs/sdks.md). To move code to the new SDK, use the
> [`pierre-migrate`
> skill](https://github.com/pierrecomputer/skills/tree/main/skills/pierre-migrate).

Git notes allow you to attach metadata to commits without modifying the commit itself. Notes are
written to `refs/notes/commits` by default. Pass `ref` to create the note on another notes ref.

`createNote()` creates a new note and fails if the target already has a note on the selected notes
ref. To replace a note, call `deleteNote()` first, then create the new note.

See [Git Notes](https://code.storage/docs/repos/git-notes.md) for notes ref rules and write behavior.

```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
const result = await repo.createNote({
  sha: 'abc123def456...',
  note: 'Build passed - deployed to staging',
  ref: 'ci', // optional
  author: { name: 'CI Bot', email: 'ci@example.com' },
  expectedRefSha: currentNotesRefSha, // optional optimistic lock
});

console.log(`Note created, new ref: ${result.newRefSha}`);
```

```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
result = await repo.create_note(
    sha="abc123def456...",
    note="Build passed - deployed to staging",
    ref="ci",  # optional
    author={"name": "CI Bot", "email": "ci@example.com"},
    expected_ref_sha=current_notes_ref_sha,  # optional optimistic lock
)

print(f"Note created, new ref: {result['new_ref_sha']}")
```

```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
// Create a git note
result, err := repo.CreateNote(context.Background(), storage.CreateNoteOptions{
	SHA:  "abc123def456",
	Note: "Build passed - deployed to staging",
	Ref:  "ci", // optional
	Author: &storage.NoteAuthor{
		Name:  "CI Bot",
		Email: "ci@example.com",
	},
	ExpectedRefSHA: currentNotesRefSHA,
})
fmt.Printf("Note created, new ref: %s", result.NewRefSHA)
```

## Options

**sha** `string` *required*

Commit SHA to attach the note to

**note** `string` *required*

Note content

**ref** `string`

Notes ref to create the note on. Accepts short names like `ci`, `notes/ci`, or full refs like
`refs/notes/ci`; all are normalized to a full `refs/notes/*` ref. Defaults to
`refs/notes/commits`. Go: `Ref`.

**author** `string`

Author signature (`name` and `email`)

**expectedRefSha** `string`

Expected SHA of the target notes ref for optimistic concurrency control

**ttl** `string`

Token TTL. Token TTL in seconds.

**refPolicies** `object[]`

Ordered ref policy rules (`{ pattern, ops? }`) in the JWT for this call. Code Storage checks the target notes ref. Python: `ref_policies`. Go: `RefPolicies` with type `storage.RefPolicyList`. See [Ref Policies](https://code.storage/docs/repos/ref-policies.md).

## Response

**sha** `string`

The commit SHA the note is attached to

**targetRef** `string`

The canonical notes ref that was updated

**baseCommit** `string`

Previous notes ref commit SHA

**newRefSha** `string`

New notes ref SHA after the operation

**result** `object`

Operation result with `success`, `status`, and optional `message`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.