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

# createNote()

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

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](/docs/guides/git-notes) for notes ref rules and write behavior.

<CodeGroup>
  ```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)
  ```
</CodeGroup>

## Options

<ParamField path="sha" type="string" required>
  Commit SHA to attach the note to
</ParamField>

<ParamField path="note" type="string" required>
  Note content
</ParamField>

<ParamField path="ref" type="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`.
</ParamField>

<ParamField path="author" type="string">
  Author signature (`name` and `email`)
</ParamField>

<ParamField path="expectedRefSha" type="string">
  Expected SHA of the target notes ref for optimistic concurrency control
</ParamField>

<ParamField path="ttl" type="string">
  Token TTL. Token TTL in seconds.
</ParamField>

<ParamField path="refPolicies" type="object[]">
  Ordered per-ref policy rules (`{ pattern, ops? }`) embedded in the per-call JWT. Evaluated against the target notes ref. Python: `ref_policies`. Go: `RefPolicies` with type `storage.RefPolicyList`. See the [Branch Protection guide](/docs/guides/branch-protection).
</ParamField>

## Response

<ResponseField name="sha" type="string">
  The commit SHA the note is attached to
</ResponseField>

<ResponseField name="targetRef" type="string">
  The canonical notes ref that was updated
</ResponseField>

<ResponseField name="baseCommit" type="string">
  Previous notes ref commit SHA
</ResponseField>

<ResponseField name="newRefSha" type="string">
  New notes ref SHA after the operation
</ResponseField>

<ResponseField name="result" type="object">
  Operation result with `success`, `status`, and optional `message`
</ResponseField>