New project

We store only identifiers — the Jira project key and a repo name. The runner on your machine maps the repo name to a local checkout and holds all credentials.

What comes after "Create" — the runner-side setup

0
Install & enroll the runner (first time only)
On the machine that holds your code and credentials (Node 20+, git and Claude Code installed).Enrolment token: Dashboard → scroll to the Runners section → Add runner. A tpe_… token appears — single use, valid 24h, shown exactly once (we store only its hash) — together with a ready-made install one-liner you can paste as-is.Or by hand:
```
npm install -g allwright
allwright init
```
init asks for three things — control plane URL: , that enrol token, and your Jira credentials (stored on that machine only, never sent to us). Token expired or lost? Click Add runner again — old tokens die harmlessly. Then make it a service (starts on boot, restarts on crash):
```
sudo env "PATH=$PATH" allwright service install
```
1
Map the repo on the runner
On the runner machine, clone the repo and map it by the exact name used above — for example:
```
git clone <acme/backend repo URL> ~/projects/backend
allwright repo add "acme/backend" ~/projects/backend
```
The path is the folder that CONTAINS the .git directory — normally just the cloned folder itself. (Downloaded a zip? It often extracts one level deep — find the real folder with find ~/projects -maxdepth 3 -name .git -type d.) Private repo? Clone with a read PAT or a deploy key from ITS GitHub org.
Then restart the runner so it picks the mapping up — only when the Runs page shows nothing running (a restart mid-run kills that run):
```
sudo systemctl restart allwright   # if installed via 'service install'
# background mode instead:  allwright stop && allwright start
```
2
Jira access for this project
The runner's main Jira credential (from init) is used automatically. Only if this project lives on a different *.atlassian.net site than that credential, give this repo its own:
```
allwright jira set "acme/backend"
```
Verify with allwright jira show.
3
GitHub token covers this repo (needed for Implement rules)
By default the runner uses one shared GitHub token. If it's a fine-grained PAT, edit it on GitHub and add acme/backend to its repository list (contents: write, pull requests: write) — or give this repo its own, separately revocable token:
```
allwright github set-token          # shared, all repos
allwright github set "acme/backend"   # this repo only
```
Watch the org: a fine-grained PAT only covers ONE GitHub organisation. If this repo lives in a different org than your other projects, the shared token will 404 on the first PR — give this repo its own token (github set above) from a PAT created in that org. Optionally, people can have personal tokens too (github user-add <email>) so PRs they trigger are authored by their own account.

CLAUDE.md in the repo root — required before rules

The agent's memory file: what the project is, how it's structured, how to run tests. Rules for this project cannot be enabled until it exists; "Test connection" on the dashboard tells you if it's missing.
Don't write it by hand — you're connecting an agent anyway, so let it do this: open claude (or Codex) inside the repo checkout on the runner machine and paste this prompt, then review & commit what it writes:

Explore this repository thoroughly, then create a CLAUDE.md file in the repo root. It is the memory file an automation agent reads before working on tickets here, so be factual and specific to THIS repo: what the product does, the tech stack and key directories, exact commands to install dependencies / build / run tests, code conventions worth following, and gotchas (things that look obvious but aren't). Keep it under ~150 lines. Do not invent anything you cannot verify from the code.

DEPLOY.md in the repo root — only if this project will deploy

Skip this if the project has no deploys yet — rules, audits and chat only need CLAUDE.md; write DEPLOY.md when a real deploy process exists, not before. It is the deploy contract: environments, branches, exact commands, which $SECRETS they use. Environment setup and "Ask for steps" refuse to run without it — the suggester only translates this file, it never guesses. Same trick as CLAUDE.md — paste this in your agent inside the repo, and review every command before committing (they run as-is on your server):

Inspect this repository (deploy scripts, CI files, server configs) and then create a DEPLOY.md file in the repo root. It is a deploy contract that an automation tool will follow LITERALLY, so only write what is actually true. For each environment (e.g. staging, production): its name, the branch it deploys from, the exact shell commands to deploy, secrets referenced as $NAMES only (NEVER values), and any checks to run before or after. If you cannot determine how deploys really work from the repo, ASK me instead of guessing — a wrong command here runs on a real server.

Secrets themselves go on the runner:

allwright env set "acme/backend" <envName> "NAME=value" …

6
Team: who acts as whom
Each person who'll use the Board or Compose needs their own Jira credential on the runner (their clicks post under their Atlassian identity, and are refused until this is set):
```
allwright jira user-add <their-ticketpilot-login-email>
```
Link Jira accounts and (optionally) per-person Claude profiles on the Team page. Deploy approvals from Jira require the approver's account to be linked.
7
Removing a project later (both sides)
Dashboard: the Delete button on the project row (owners/admins) — removes its rules, environments and run history; refused while runs are active. Then on the runner:
```
allwright repo remove "acme/backend"   # unmaps + clears its secrets/overrides
# optional: delete the checkout folder yourself, then restart the runner
```
Jira tickets and the GitHub repo are never touched by either step.
8
Create a rule and test it
Add a rule (e.g. trigger /ask → action Answer) on the dashboard, hit Test connection — it checks the repo mapping, Jira access, CLAUDE.md and DEPLOY.md in one go and lists exactly what's missing.