• Setting up a project/roadmap -- create the Project, fields (Status, Priority), the Epic + Upcoming views, enable native workflows
• Creating an epic with issues -- "make an epic X with these issues", "group these under an epic"
• Filing / moving work -- attach an issue under an epic, move an issue between epics, add new work
• Driving the board -- pick up an issue (-> In Progress), close one (-> Done), (re)prioritize
• Classifying work -- set native issue Types (Task/Bug/Feature) instead of type labels
• Milestone scoping -- create a milestone for a deliverable, assign issues, close it out; resolve "current milestone" / "milestone N"
• Migrating an existing repo's loose issues into this structure
• Configuring tool allowlists -- auto-approval patterns for read-only

  gh project

  commands

1. Epics nest by native sub-issues, NOT markdown checklists. A

   - [ ] #123

   bullet is cosmetic; it does not create the parent/child link the UI and roadmap read. Link natively:

   gh issue edit <epic> --add-sub-issue <child>

   /

   gh issue create --parent <epic>

   (gh >= 2.94), or the REST sub-issues API. See

   references/sub-issues.md

   .
2. Moving an issue between epics = re-parent the native link. One command:

   gh issue edit <child> --parent <newEpic>

   (replaces the old parent), then tidy body text. Editing bullets alone leaves it under the old epic -- the most common "looks moved but isn't" miss.
3. The board Status is not automatic. Closing an issue does not set

   Done

   unless the native Item closed workflow is enabled. Set Status explicitly, or enable the native workflows once (see

   references/project-setup.md

   ).
4. Single-selects (Status, Priority) are set by option ID, not name. Look up field IDs + option IDs first (

   gh project field-list <num> --owner @me --format json

   ), then

   item-edit

   . Names silently no-op.
5. Views and workflow-enabling are one-time UI; everything else is scripted. There is no API to create/rename a view or toggle a workflow. Do those once in the UI (or copy a template); script the rest.
6. Type and Milestone are issue metadata, NOT project fields. Set them on the issue (

   gh issue edit <n> --type Bug --milestone "v1.0"

   ); the board mirrors them as built-in columns for grouping/filtering, but

   gh project item-edit

   cannot touch them and they never appear in

   field-list

   . Issue types exist only in org repos. See

   references/types-and-milestones.md

   .

• GitHub only -- Projects v2 has no GitLab equivalent.

• gh

  >= 2.94 for the native issue flags used here (

  --type

  ,

  --milestone

  ,

  --parent

  ,

  --add-sub-issue

  ); older

  gh

  falls back to the REST recipes in the references.
• Token scopes gate what works.

  gh auth status

  shows them.

  gh project

  commands and any

  projectV2

  GraphQL need the

  project

  scope (

  gh auth refresh -s project

  );

  read:project

  alone is enough for read-only queries. Without the scope these fail with auth/permission errors even though everything

  repo

  -scoped works -- the classic "project features seem missing" trap. Issues, sub-issues, types, and milestones ride on the ordinary

  repo

  scope; org-owned project access also relies on

  read:org

  .
• Projects are addressed by number under an

  --owner

  (

  @me

  or an org login). The repo and project may have different owners. For an org-owned project, pass the org login to

  --owner

  , and in GraphQL reads use

  organization(login: "ORG") { projectV2 }

  instead of

  viewer { projectV2 }

  (see

  references/cli-and-graphql.md

  ).

Reference:

references/project-setup.md

-- end to end: create the Project, add

Status

/

Priority

(and optional

Stage

) fields, build the Epic and Upcoming views (UI -- no API), enable the native workflows (Item added, Auto-add sub-issues, Item closed -> Done), the optional template-copy fast-path, and the migration playbook for an existing repo.

gh project create --owner @me --title "Roadmap"
gh project field-create <num> --owner @me --name "Priority" --data-type SINGLE_SELECT \
  --single-select-options "P0,P1,P2,P3"
gh label create epic --color B60205 --description "Roadmap epic"

• Read-only (safe to auto-approve):

  gh project list/view/field-list/item-list

  , GraphQL read queries,

  gh label list

  ,

  gh issue list/view

  , milestone reads (

  gh api repos/{owner}/{repo}/milestones

  ), issue-type reads (

  gh api orgs/{org}/issue-types

  )
• Write (require approval):

  gh project create/copy/edit/link/field-create/item-add/item-edit/item-archive/item-delete

  ,

  gh label create

  ,

  gh issue create/edit

  (incl.

  --type/--milestone/--parent/--add-sub-issue

  ), milestone

  POST

  /

  PATCH

  /

  DELETE

  , sub-issue

  POST

  /

  DELETE

  , GraphQL mutations

Reference: See

references/allowlist.md

for read-only

gh project

patterns and the opt-in write set.

1. Native links, not checklists -- the tree is built from sub-issue links; bullets are decoration (rule 1).
2. Re-parent to move --

   gh issue edit <child> --parent <newEpic>

   ; body edits alone don't move it (rule 2).
3. REST sub-issues take the database

   id

   -- if you drop to

   gh api .../sub_issues

   , fetch it with

   --jq .id

   ; the issue number won't work (the native

   gh

   flags take numbers/URLs).
4. Single-selects set by option id -- discover ids with

   field-list --format json

   before

   item-edit

   .
5. Views + workflow toggles are UI-only -- no API; do them once (or copy a template) (rule 5).
6. Sub-issue mutations batch ~25/request -- larger batches hit

   RESOURCE_LIMITS_EXCEEDED

   ; a multi-

   --add-sub-issue

   edit can partially fail on the same limit -- re-running is safe.
7. Type/Milestone are not project fields -- set on the issue, mirrored on the board;

   item-edit

   can't set them and

   field-list

   won't show them (rule 6). Types are org-only (

   --type

   on a personal repo:

   type "..." not found; available types:

   -- fall back to labels there).
8. "Current milestone" = smallest due date among open (past-due included); "milestone N" = number N, not the Nth open (see

   references/types-and-milestones.md

   ).