Docs and Git over SSH

The docs space

Every project has a documentation space: a tree of pages for specs, decisions, runbooks and meeting notes, kept next to the project's tasks. Open it from the project's Documents tab, or see every space in your organisation under Docs in the sidebar.

Behind the scenes each space is a real Git repository of Markdown files. Edits in the browser are committed for you; developers can clone the same repository over SSH, edit in their own editor and push. Both stay in sync.

Writing in the browser

Press + Create for a new page, or e on a page to edit it; Ctrl/⌘ + S publishes. Type / for blocks:

• text, headings 1–4, bullet and numbered lists, QC checklist, quote, code block, table, divider;
• diagrams (Mermaid), charts, callouts, status lozenges and images;
• links to pages, smart links to tasks or pages, a live Tasks list, child pages and a table of contents.

Pages have a status — Draft, Review or Approved — and labels you can filter by in the sidebar, which also lists recently updated pages. You can mention teammates with @. From a page's actions menu you can copy its link, rename, duplicate, move it, export it as Markdown or PDF, view its source, see its history (with diffs and restore), or delete it.

Docs and tasks together

• Create a task from a page: select text and press Create task, right-click and choose Create task…, or use the page's actions menu. Pick the title, epic and status; a smart link to the new task is inserted in the page.
• Link the other way: any page that links to a task (or mentions #KEY) shows up in that task's Linked pages, so whoever picks up the task — person or AI agent — finds the spec.

Add an SSH key

1. If you don't have a key yet, create one:

ssh-keygen -t ed25519 -C "you@example.com"
cat ~/.ssh/id_ed25519.pub

2. Open Account → SSH keys, give the key a name (e.g. “Work laptop”) and paste the public key — the single line from the .pub file.
3. Test the connection:

ssh -T -p 2222 git@planner.uniqtech.dev

A reply of Hi <your name>! UQ Planner docs does not provide shell access. means it works — the non-zero exit code is normal.

Accepted keys: Ed25519 (recommended), ECDSA (P-256, P-384, P-521) and RSA of 2048 bits or more. DSA keys are refused. You can add up to 10 keys, and a key can belong to only one account.

Clone the docs

In the docs space, press Clone. It shows the exact URL for that project, ready to copy. URLs look like this:

ssh://git@planner.uniqtech.dev:2222/<org-slug>/<project-slug>.git

git clone ssh://git@planner.uniqtech.dev:2222/acme/website.git
cd website

The organisation slug comes from your organisation settings; the project slug from the project's short code (or its name). The public Git server is planner.uniqtech.dev on port 2222.

Optional: an SSH config entry

Host planner.uniqtech.dev
  Port 2222
  User git

Keep the docs inside your code repository

git submodule add ssh://git@planner.uniqtech.dev:2222/acme/website.git docs/plan

Who can clone: members of the project, organisation Owners and Admins. Access is checked on every connection, so removing someone from the project cuts off Git access too.

Edit and push

# edit Markdown in your editor, then
git add .
git commit -m "Document the release checklist"
git push origin main
git pull   # Planner may add a small follow-up commit — pull before your next push

• Only the main branch can be pushed. Force-pushes and deleting main are refused.
• Pushed pages appear in the web app straight away and are searchable.
• After a push, Planner may add a follow-up commit that fills in missing page details (id, title, order) and refreshes generated blocks. The push output tells you; run git pull before pushing again.
• Pushing isn't possible in an archived project.

How files map to pages

Each Markdown file can start with front matter that Planner reads and keeps:

---
title: Local setup
status: review        # draft | review | approved
owner: dev@example.com
tags: [onboarding]
---
# Local setup

Clone the app, then…

Recognised keys are id, title, icon, order, format, status, owner and tags; anything else is preserved untouched. Leave id out of new files — Planner adds it.

Rules and limits

• File and folder names: lowercase letters, digits, ., _, - and /; up to 255 characters and 10 levels deep.
• Up to 10 MB per file and 200 MB per space.
• Up to 10 labels per page.
• index is reserved everywhere; readme and assets are reserved at the top level.

Git errors and fixes

Too many failed sign-ins from one address in a minute trigger a short block — wait a minute and retry with the right key. More help in the FAQ.