Your code

Write @gitian:<category> in a normal comment. The rest of the line, and the comment lines after it, are the description; --key=value lines add metadata. The annotation stays in the same file and commit as its code, so it moves when the code moves and goes when the code goes.

// @gitian:security  Validate the redirect before setting the cookie.
// --id=SEC-014
// --group=auth
// --urgency=critical
export function completeLogin(redirect: string) {
  assertSameOrigin(redirect);
  …
}

Built-in categories: todo, note, warning, deprecated, security, bug, perf and api. Define your own under tags: in .gitian/config.yaml. Each category has one of four kinds:

marker

A line in a collapsible checklist, with no code. For todo.

inline

A small card with no code.

block

A card that captures the code right below it, by braces, Nix brackets, JSX elements or Python indentation. Put it directly above the function or class.

api

An API card with Request and Response panels, taken from other annotations named by --request= and --response=. Works for REST, gRPC, webhooks and the rest.

Two more tiers are off until you turn them on in config: doc-comment tags such as @param and @deprecated (detect_docs), and bare TODO or FIXME keywords (detect_keywords). They render muted and capture no code. The Gitian GitHub App can also comment on a pull request with what it did to your annotations, set under pr_analysis.

Put markdown in a docs/ or .docs/ directory, at any depth. A file named after a source file plus .md documents that file in the directory above; docs/payments.md documents a sibling payments/ directory; any other file is a page of its own. All of them merge into one set, so links resolve across the whole repository.

repo/
├─ src/
│  ├─ auth.ts
│  └─ docs/
│     └─ auth.ts.md     documents src/auth.ts
├─ services/
│  └─ .docs/
│     └─ sync.md        a page of its own
└─ .gitian/
   └─ config.yaml       optional

A paired file opens with two tabs: the rendered doc and the highlighted source.

Directives

Embed live annotations in a doc. {{annotation:SEC-014}} shows one by its id, {{annotation:#auth}} every one in a group, and {{annotation:@security}} every one in a category. They render from the code each time, so the page never holds a stale copy.

Markdown that reads correctly in Obsidian renders correctly here, straight from the ref you are viewing, with no build step and nothing to host.

• Wikilinks: [[Page]], [[Page|label]], [[Page#Heading]].
• Callouts: > [!note], > [!warning], > [!tip], nested if you like.
• Mermaid diagrams in code fences, and KaTeX math inline or as a block.
• Tables, task lists, footnotes, strikethrough, highlighted code, and YAML front matter.

Rotation follows [[CONTRIBUTING#Auth Flow]]; the older
handshake is [[legacy-auth|the v1 flow]].

> [!warning] Replay window
> Refresh tokens rotate on use. $t_{expiry} = t_{issue} + 900s$

```mermaid
flowchart LR
  A[client] --> B{token valid?}
  B -->|yes| C[rotate + issue]
  B -->|no| D[401]
```

GitHub repositories today. Obsidian is a trademark of its owners; Gitian is not affiliated with it.

A knowledge-base item can point at the code it is about. In the body, write a link; in the front matter, list the code the whole item is about under code_refs.

[[repo:owner/name[@ref]/path#anchor|label]]

…/src/auth.ts

The file.

#refreshToken

A symbol. A member is #Client.refresh.

#L10-L20

A line range. Lines drift, so pin it to a ref.

#@auth-refresh

An annotation by its --id. The anchor that survives edits best.

@v2.1.0

After the repository name: a branch, tag or commit. Leave it off to follow the default branch.

|label

Display text. Not part of the link.

Agents should not type these. With the code server connected, code_search, code_page and code_annotation hand back code_ref (follows the branch), code_ref_pinned (frozen at the commit read, for line ranges and claims about the past) and code_refs_entry (for the front matter list).

Readers see a chip, or a card when the link is alone in its paragraph, and a preview of the code on hover or focus. Access is checked when the item is read, against the reader: without access to the repository they see a lock, never the code, and a missing target shows struck through. The knowledge base stores the pointer, never the code.

Pull requests

An item can also point at the pull request that implemented it, or the one that broke something. Write the link in the body; a pasted pull request URL counts as the same reference.

[[pr:owner/name#42]]
[[mr:gitlab.com/group/project!42]]

[[pr:…#N]]

A GitHub pull request. Another forge puts its host first: [[pr:codeberg.org/owner/name#42]].

[[mr:…!N]]

A GitLab merge request. The prefix and the sign are interchangeable.

A pasted URL

A GitHub, GitLab, Forgejo, Gitea or Bitbucket pull request address, bare or as the target of a markdown link.

pr_refs

Front matter: the pull requests the whole item is about, each a repository and a number, or a short string such as acme/api#42.

|label

Display text. Not part of the link.

Readers see a chip with the pull request's state (open, draft, merged or closed) and its title, and a card when the link is alone in its paragraph. As with code, access is checked against the reader: without access to the repository they see only the reference. In the repository viewer, a pull request's Knowledge tab lists the items that point at it, and a file shows the pull requests that touched it. An annotation can name its own with a --pr= line, which shows as the same chip.

Agents should not type these either. code_prs lists a repository's pull requests and code_pr reads one; each returns pr_ref, the link to paste. They read a synced copy of pull request metadata, never a description or a comment.

Every repository opens at /r/<owner>/<repo>/<ref> with a dashboard of its annotations, docs, languages, recent commits and releases. Public repositories open without signing in. For a private one, sign in and install the Gitian GitHub App on the repository or its org.

Click a line number to select it; right-click to copy a Gitian link, a GitHub permalink or the line. A file that knowledge-base items point at shows them in an "In the knowledge base" panel, with markers beside the lines they name. Explore the demo repository.