Wiki

Overview

A wiki is the documentation that belongs to a repository or a group but is not part of its code: the explanation of how something works, the decision nobody wrote down, the runbook somebody needs at three in the morning. You write it in the browser, it is versioned in git, and it lives beside the thing it documents instead of in a tool nobody opens.

Keeping it in git rather than in a database is what makes it recoverable. Every save is a commit with an author and a message, every page has a history you can read, and nothing is ever silently overwritten — if two people edit the same page at once, the second one is told rather than losing their work.

A wiki is separate from the code repository on purpose. A typo fix in the documentation is not a code commit: it does not open a pull request, does not start a pipeline, and does not appear in anyone's contribution graph. When you would rather it did all of those things, point the wiki at a directory in the repository instead — see Where pages come from.

Before you start

How it works

A wiki is off until somebody turns it on

Reading a scope that has never had a wiki does not fail — it answers enabled: false. Whether a wiki exists is not a secret; only its contents are. Turning one on creates it, and turning it off later hides its pages without destroying anything, so switching it back on returns everything exactly as it was.

Where pages come from

A wiki reads its pages from one of two places, and you choose which when you turn it on.

• Its own history is the default. Pages are edited in the browser, each save is a commit, and none of it touches your code.
• A directory in the repository is the alternative. Point the wiki at a path on the default branch and it shows what is committed there. Editing through the wiki is refused, because the way to change the file is to change the file — which means the documentation goes through the same review as the code, which is usually the reason people want this.

Switching between them changes what you read, never what is stored: the pages you wrote in the wiki's own history are still there if you switch back.

A page's address and its name are different things

A page's path is where it lives — guides/getting-started — and it is also the name of the file. A page's title is what a person reads, and you can change it without moving the page. Slashes in a path make folders, so the tree organises itself.

Renaming a page changes its address and nothing else. Everything that pointed at the page keeps pointing at it, and the old address keeps working: open it and you land on the page with a note saying where it went. That holds however many times a page moves.

Two people editing one page

Every save carries the version of the wiki you started from. If somebody else saved while you were typing, your save is refused with a 409 rather than quietly replacing their work — reload, take in what changed, and save again.

This is the one place the wiki will interrupt you, and it is deliberate: losing an edit silently is the thing that stops people trusting a wiki.

Deleting a page keeps its links honest

A deleted page is remembered. Its address stops serving content, but everything that linked to it is still reported as linking to something that is gone — so a broken link shows up as broken instead of disappearing along with the page.

How to

Turn on a wiki

Open the repository or group, choose Wiki, and create the first page. Through the API, PATCH /repositories/{repo_id}/wiki with {"enabled": true}.

Read the page tree

GET /repositories/{repo_id}/wiki/pages returns pages in path order, so the result is already the tree. Pass prefix to fetch one folder, and limit and next_token to page through a large wiki.

Read one page

GET /repositories/{repo_id}/wiki/pages/{path}, with the path URL-encoded — guides%2Fgetting-started. You get the content, the page's headings for building a table of contents, and, if you asked for an address the page has moved away from, a redirected_from telling you so.

Write a page

POST /repositories/{repo_id}/wiki/pages with a path, a title and the content. Add a message to say why in the history; without one, a sensible message is written for you.

Change a page

PUT /repositories/{repo_id}/wiki/pages/{path}, including expected_head_sha — the version you read before you started editing. That field is what stops two people overwriting each other, so it is required.

Move or rename a page

POST /repositories/{repo_id}/wiki/pages/{path}/move with new_path. The old address keeps resolving, and the page's history follows it across the move rather than starting again.

Delete a page

DELETE /repositories/{repo_id}/wiki/pages/{path}, with expected_head_sha for the same reason a change needs one.

Read a page's history

GET /repositories/{repo_id}/wiki/pages/{path}/revisions returns the commits that touched it, newest first, following the page through any renames.

Add an image or a file to a page

POST /repositories/{repo_id}/wiki/attachments with the filename and its content type. You get back an id and a short-lived upload URL; send the bytes to that URL with PUT, then link to the file from a page.

Reading one is GET /repositories/{repo_id}/wiki/attachments/{attachment_id}/{filename}, which redirects to the file. A single-page app should pass redirect=false to get 200 { "url": … } and navigate to the URL itself, because a browser cannot follow a redirect that carried your credentials to a different host.

Files are downloaded rather than displayed in place. That is deliberate: they are your uploads served from our address, and rendering them here would let one page's file run as part of the site.

Anyone who can read the wiki can read what its pages link to, and Developer is needed to add or remove a file. Deleting a page does not delete the files it linked to.

Do all of this on a group

Every path above has a group twin: /groups/{group_id}/wiki/…. The bodies, the responses and the permissions are identical.

Reference

Everything in this section — paths, parameters, shapes, scopes and errors — is generated from the API itself.

Page paths. Segments are separated by /, and each one starts with a letter or a digit and then allows letters, digits, ., _, - and spaces. A segment is at most 245 bytes, and the whole path at most 1000. templates/ and attachments/ are reserved.

Formats. Pages are Markdown. The other markups a wiki file can carry — AsciiDoc, reStructuredText, Org, Textile and MediaWiki — are recognised when a wiki is imported, so a page written elsewhere keeps its extension and still appears.

Limits

A deleted page releases its slot. Past the page limit, creating a page answers 429; raise it by moving to a larger plan, or by asking for an increase.

Attachment downloads count against your namespace's outbound traffic, the same way release downloads and clones do.

Troubleshooting

FAQ

Next steps

Related