Projects and fields

Projects lists the GitHub Projects belonging to the connected organization or account, with their fields and the issues on them, and creates one.

Pealboard does not have a project type of its own. A project is a GitHub Project; a field is a GitHub project field. Pealboard reads them, uses them as dimensions to filter, sort and group by, and writes a value back when you change one. New project creates one in GitHub — not a Pealboard object that syncs to one — so it is on github.com the moment it is made, and it stays there if you stop using Pealboard.

Field types Pealboard uses

GitHub field type	Read	Set from Pealboard	Filter, sort, group
Single select, including Status	Yes	Yes	Yes
Number	Yes	Yes	Yes
Date	Yes	Yes	Yes
Iteration	Yes	Yes	Yes
Text	Yes	Yes	Filter only
Title, Assignees, Labels, Milestone, Repository	Yes	On the issue itself	Yes

Status is a field, not a state

GitHub issues have two states: open and closed, and closed carries a reason, Completed or Not planned. Status is something else: a single-select field on a project, whose options the project owner writes — Triage, In progress, Blocked, Done, or whatever the team decided.

Pealboard uses both, and never confuses them. A board grouped by Status moves a project field. A board grouped by state moves nothing; state changes when you close or reopen the issue.

Create a project

Projects → New project asks for four things and makes one call:

Project title	What GitHub shows at the top of the project.
Description	The line under the title on GitHub’s project list. It can be changed later but not removed: GitHub keeps the last one.
Status options	The columns of the project’s Status field, in order. GitHub starts a project with Todo, In Progress and Done; the names you type replace them, two to ten of them, all different. The names you see are the names GitHub is given.
Add issues	Issues to put on the project as it is created. Each becomes an item. You can add more afterwards, here or in GitHub.

The project is created in GitHub first and cached afterwards, like every other write in Pealboard: if GitHub refuses, you see GitHub’s refusal and nothing was made.

Edit project changes the title and the description. Delete project deletes it in GitHub, for everybody in the organization, and GitHub does not undo it — so it needs the admin role, and it is refused while a request type still names the project as a destination. The issues that were on a deleted project are untouched: a card is not the issue. Neither is offered on a personal account; see below.

Two things GitHub does not let an app do

Visibility. A new project is private, and Pealboard cannot change that. GitHub refuses a visibility change from an app whatever the value is — even to the value the project already has — so making a project public is done in the project’s own settings on GitHub. Pealboard refuses the request rather than reporting a write that did not happen.

Projects on a personal account. GitHub’s Projects permission is an organization permission, and there is no personal-account equivalent for an app to be granted — not for Pealboard’s app, and not for your own linked GitHub account either: a GitHub App issues that token too, bound to the app’s own permissions rather than to what you could otherwise do on your own account. So when the workspace is connected to a personal account rather than an organization, Pealboard cannot create, edit or delete a project there at all. New project, Edit project and Delete project are not offered; in their place:

GitHub does not let an App create a project on a personal account. Create it on GitHub; it appears here on the next sync.

Create the project on GitHub directly, at https://github.com/users/<your account>/projects/new, and edit or delete it there too. Pealboard picks up the change on the next sync — press Sync now on Settings → GitHub, or wait for the hourly reconciliation. Everything else about the project — its fields, its items, its board — works the same either way.

Renaming a Status option afterwards

The Status names can be set while the project is being created and not after. GitHub replaces the whole option set on a rename and issues new option ids, so renaming one once cards are on it is a decision about those cards — and that decision belongs on GitHub’s own board, where you can see them.

Adding an issue to a project

Open the issue and choose a project in the Fields panel. The issue becomes an item in that project, exactly as it would if you had added it in GitHub. Initial field values can be set at the same time.

A request type can add every issue it creates to a project and set field values on creation, so a new request arrives already in Triage.

The items list

Projects → a project lists its items, most recently changed first, with each field value editable in place. Add issue searches every connected repository and adds one; Remove from project removes the card and leaves the issue alone — it stays in its repository, keeps its labels and its comments, and can be added again.

Pealboard stores no ordering for project items. GitHub’s own board keeps one, and maintaining a second copy of it under out-of-order webhook deliveries would be a cost paid for a value only that board reads. So the list is ordered by what changed most recently, and the only move Pealboard offers is Move to the top, whose result is read on GitHub.

What Pealboard never does to a project

• It does not create, rename or delete fields, or add options to a single-select field. The one exception is the Status options, which New project names while GitHub is creating the project.
• It does not create or edit a project’s built-in automations. GitHub exposes no way to author those through its API; the four built-in rules a project already has continue to run and Pealboard does not interfere with them.
• It does not read a project’s Insights charts. GitHub has no API for them.

If you need a new field or a new option, add it in GitHub. Pealboard sees it on the next sync.