Centerboard documentation

Getting started

1. Create an account with an email and password, or with Google.
2. Accept the Terms of Service. The version you accept is recorded.
3. Choose A project on GitHub, connect a GitHub token scoped to project, and enter a repository you own as owner/repository.
4. Centerboard creates the sprint board and opens it.

The GitHub token

Boards use a classic personal access token scoped to project and nothing else. Create one here, with only the project box ticked. It lets Centerboard read and move the cards on your boards; it cannot read, change or delete your code. Centerboard keeps the token, which is why it refuses one that can reach more.

Centerboard refuses a token that carries more. A token with repo would hand over every repository you can see, and no board needs that. The error tells you which scopes were the problem.

The token is encrypted at rest with a key that is not stored in the database. You can disconnect it from Settings at any time, and it stops working immediately.

Boards and columns

Each connected repository gets a GitHub Projects (v2) board with six status columns. The board is a real GitHub board: anything you do on github.com shows up in Centerboard, and the reverse.

The six, in order: Backlog, Not Started, In Progress, Blocked / Review, Recently Completed, Done. If you attach a board you already have, Centerboard uses whatever columns it already has and does not rename them.

• Add an item from the composer under the board. It is created on GitHub as a draft issue.
• Change an item's status from its dropdown; the change is written to GitHub. Choosing Done asks you to confirm, then records your name against the card: Done is only ever set by a signed-in person.
• Completion is computed from where each item sits between the first and last column.
• An item marked Done by an automated run lands in Recently Completed instead, so a human confirms it. Goals only count Done.

GitHub Projects is eventually consistent: a fresh item can take a few seconds to read back. That is GitHub, not a bug.

Card refs, and moving a card from a commit

Every card carries a short ref like CB-7, shown on the card and copied by clicking it. Put that ref in a commit message and the card moves itself.

git commit -m "CB-7 add the booking form"

• A push whose commit message or branch name contains the ref moves that card to In Progress.
• A merged pull request naming it moves it to Recently Completed. A push is never treated as evidence that something is finished.
• Nothing moves backwards, nothing moves out of Blocked / Review, and nothing an automated run does ever lands on Done.

A card gets its ref the first time Centerboard reads the board, so refs appear once the board is attached to a project. Refs are never reused: one that has been written into a commit message stays with that card for good.

Card movement needs unattended runs switched on for the project, in Settings.

The phone board

dashboard.centerboard.dev/board is the same board as a thumb-friendly list. Add it to your home screen. Moving a card there moves it on GitHub.

Goals

A goal is a named outcome, such as First paying customer, that groups board items. A goal's progress counts only items in Done. Goals live in Centerboard, not on GitHub.

Bringing your own model

Centerboard is hosted software. There is nothing to download, nothing to self-host, and no client to keep updated. You keep working in whichever model you already use, and it talks to Centerboard over the connector.

Getting a key

Open Settings and create a connection under Connections. The key is shown once, because only a hash of it is stored, and you can revoke it at any time. Revoking takes effect on the next request. Send it as a bearer token:

Authorization: Bearer cbk_...

A key identifies one account. Every call is scoped to that account, and a project belonging to somebody else answers 404 rather than 403, because a 403 would confirm it exists. A sign-in session is not a key and will not be accepted as one.

What a model can do

Call	What it gives back
GET /api/connect/whoami	The account the key belongs to, and its projects.
GET /api/connect/projects/:id/board	The board: columns, cards, completion.
GET /api/connect/projects/:id/next	The next card worth picking up, and the goals it belongs to.
GET /api/connect/projects/:id/goals	Goals, and how many cards each groups.
POST /api/connect/projects/:id/items	Add a card. { title, body? }
POST /api/connect/projects/:id/items/:itemId/status	Move a card. { optionId }

/next is the one that matters. Your model asks a single question rather than being handed a prompt you maintain by hand.

Two things it will not do

A model cannot mark its own work done. Moving a card to Done lands it in Recently Completed, for a person to confirm. Goals count only Done, so without this an unattended run could report a goal complete with nobody looking. The response says so rather than quietly correcting the caller.

/next will not offer work you marked off limits. Cards labelled Safety-critical are skipped, and a project with automation turned off returns no card and says why.

The connector reads and writes the board and nothing else. It has no access to your repositories, your credentials, or your goals: your model already has the code, and goals are how a person decides what matters. Every write is recorded against your account with the key's name.

The API

The hosted API lives at https://api.centerboard.dev. Authenticate with the session token as a bearer: Authorization: Bearer <token>. A token is looked up on every request, so revoking it takes effect immediately.

Route	What it does
GET /api/session	Who you are.
GET /api/credentials	Which GitHub credentials exist (never the secrets). POST /api/credentials/projects-token adds a project-scoped token.
GET /api/projects	Your projects. POST with {repoOwner, repoName} connects one.
POST /api/projects/:id/board	Creates the sprint board. GET reads it, with items and completion.
POST /api/projects/:id/items	Adds an item. POST …/items/:itemId/status with {optionId} moves it.
GET /api/projects/:id/goals	Goals. POST with {title, taskItemIds} creates or updates one.
GET /api/terms	Which terms version you accepted, and whether it is current.
GET /api/health	Public. Reports schema version and whether credentials are configured.

A row that belongs to someone else returns 404, not 403.

Your data

Your code stays on GitHub. Centerboard stores your identity, which repositories you connected, your goals, encrypted credentials, and an audit trail of actions taken on your behalf. Disconnecting a project removes it from Centerboard only; the repository and board on GitHub are untouched. The privacy notice has the full list.