Skip to content

GitHub Projects Setup Guide

Step-by-step to stand up the board defined in 12_tools_and_tracking.md inside GitHub Projects v2. Written for a team that already has (or can create) a GitHub organization. Parallel to notion_setup.md — pick one, not both.

Plan Caveats

  • Free for public and private repos on GitHub Free for organizations. No seat cost.
  • Project v2 lives at the org level. Cross-repo issues on one board.
  • Automation: built-in workflows only in this guide. GitHub Actions optional later.
  • Best fit when: software subteam already uses GitHub, CAD/docs live in a repo, team wants tight PR-to-card linking.

1. Prep the Org

  • Create org at github.com/organizations/new (free plan). Name: team-#### (replace with team number).
  • Verify the org email — required for education discount later.
  • Apply for GitHub for Education / Teacher-Student Benefits at education.github.com. Gets private-repo perks and free Copilot for approved students. Approval ~1–2 weeks.
  • Create one repo per active codebase (robot-code, scouting-app, etc.). Create one extra repo season-board to host non-code issues (business, outreach, awards). Empty README is fine.

2. Create the Project

  • Org home → Projects tab → New project → Board template.
  • Name: Season Board.
  • Visibility: Private to org (default). Public later if the team publishes retros.

3. Add Custom Fields

Project page → top-right ⋯ → Settings → Custom fields. Add each:

Field Type Options
Status (built-in) Single select Backlog, Ready, In Progress, Blocked, In Review, Done
Subteam Single select drivetrain, mechanism, software, electrical, strategy-scouting, business
Type Single select cad, fab, assembly, wiring, code, test, driver-practice, purchase, doc, sponsor, outreach, social, award-submission, media
Subsystem Single select intake, shooter, elevator, drivetrain (add as needed)
Priority Single select P1, P2, P3
Estimate Single select S, M, L, XL
Gate Single select G1, G2, G3, G4, G5, G6, G7, GB1, GB2, GB3, GB4
Deadline Date —
Flags Labels (repo) / Text (draft) blocked:part, blocked:decision, blocked:other-card, rookie-owned, safety-critical, needs-order
Acceptance criteria Text —

Status column colors: set in the Status field editor. Suggest: - Backlog = gray, Ready = blue, In Progress = yellow, Blocked = red, In Review = purple, Done = green.

Flags note: repo labels only apply to real issues. For drafts, use a Flags text field or one Single select per flag. Simpler: single select Flag with the seven values above, none default.

Matches the tag axes in 12_tools_and_tracking.md.

4. Create Repo Labels (Issues Only)

In each repo → Issues → Labels → New label. Prefix mirrors 12_tools_and_tracking.md:

  • subteam:* — blue
  • type:* — green
  • blocked:*, needs-order, safety-critical, rookie-owned — red / yellow
  • gate:* — purple
  • priority:P1, priority:P2, priority:P3 — orange

Fast path: create labels once in season-board repo, then use gh label clone <src-repo> --repo <dest> to copy into every other repo.

5. Default Board View

  • Project page → default board view is auto-created.
  • Group by: Status. Reorder columns: Backlog → Ready → In Progress → Blocked → In Review → Done.
  • Card face fields (⋯ → Fields): show Subteam, Type, Assignees, Estimate, Gate, Deadline.

6. Saved Views

Click + New view for each. Mirrors 12_tools_and_tracking.md.

View Layout Filter Group / Sort
Tonight Board status:"In Progress","Ready" Group by Subteam
By Subteam Board — Group by Subteam
Blocked Table status:Blocked Sort updated desc
Gate G1 … Gate GB4 Table gate:G1 (etc) Sort Deadline asc
Purchasing Table flag:needs-order,blocked:part —
Rookie work Table flag:rookie-owned —
Safety-critical Table flag:safety-critical status:"In Review" —
This week Table gate:<current> Sort Deadline asc
Deadlines Table has:deadline Sort Deadline asc
Business Board subteam:business Group by Status

Filter bar uses field:value syntax. Views are shared org-wide, not per-user.

7. Card Templates

For issues — per repo, add .github/ISSUE_TEMPLATE/standard_card.yml:

name: Standard card
description: Build/code/CAD task with acceptance criteria
title: "[verb-first] "
body:
  - type: textarea
    id: acceptance
    attributes:
      label: Acceptance criteria
      description: One testable sentence. See 12_tools_and_tracking.md.
      placeholder: "All four bumper mounts torque to 15 ft-lb without deflection."
    validations:
      required: true
  - type: textarea
    id: links
    attributes:
      label: Links
      value: |
        - CAD:
        - PR:
        - Part #:
        - ECR:
  - type: textarea
    id: notes
    attributes:
      label: Notes

For drafts — no template mechanism. Paste this into the body manually:

## Acceptance criteria
- [ ]

## Links
- Sponsor contact:
- Deadline:

## Notes

Enforces the rule from 12_tools_and_tracking.md: no card without acceptance criteria.

8. Draft vs Issue — When to Use Which

Issues for anything code, CAD, or repo-linked. Auto-close on PR merge. Cross-repo searchable. Full comment threads.

Drafts for capture-fast, no-repo work: business asks, sponsor calls, outreach ideas, award-submission drafts, brainstorm parking lot. Convert draft → issue via card ⋯ → Convert to issue once scoped and assigned.

Rule of thumb: - subteam:business|outreach|awards → draft first, issue only if it touches a repo (e.g., website update). - Everything else → issue in the relevant repo.

9. Built-in Automation

Project → Settings → Workflows. Enable:

Workflow Effect
Item added to project Auto-set Status = Backlog
Item reopened Status = In Progress
Item closed Status = Done
Pull request merged Linked issue → Status = Done
Auto-add to project Any issue opened in season-board (or other listed repos) auto-lands in Backlog
Auto-archive items Items in Done for > 14 days archived

Zero YAML. Covers 80% of card lifecycle.

Not covered by built-ins (accept manual or defer to Actions later): - Slack pings. - Weekly stale-card report. - Auto-label by file path.

10. Invite Team

Org → People → Invite member.

  • Roles: Member for students, Owner only for Team Lead + Lead Mentor.
  • Team structure (org → Teams → New team):
  • team-lead (1–2 people)
  • mentors
  • subteam-drivetrain, subteam-mechanism, subteam-software, subteam-electrical, subteam-business
  • Project → Settings → Manage access → grant write to all teams. admin to team-lead and mentors.

Guest cap: none — GitHub Free for orgs has unlimited members. Advantage over Notion free tier (10 guests).

11. Hygiene

Built-ins archive Done > 14 days. Rest is manual, matches 12_tools_and_tracking.md.

Sunday grooming (Team Lead + Subteam Leads): - Blocked > 2 sessions → escalate or kill. - In Review > 3 sessions → reviewer is bottleneck. - Backlog > 3 weeks with no assignee → close or defer. - Deadline view sweep — anything within 7 days highlighted.

Daily sweeps: - Purchasing Lead → Purchasing view. - Safety Captain → Safety-critical view. - Team Lead → Blocked view.

On season-board repo README, embed:

- Overview → docs/index.md
- Timeline → docs/09_timeline.md
- Build session → docs/11_build_session.md
- Tools & tracking → docs/12_tools_and_tracking.md
- Business & outreach → docs/13_business_outreach.md
- Awards → docs/14_awards_and_submissions.md

Project description (top of Project page) → paste same links.

13. First-Week Checklist

  • Org created and Education plan applied
  • season-board repo created + labels
  • Season Board Project v2 created
  • All custom fields added
  • Board view + Tonight, By Subteam, Blocked, Purchasing, Business saved views
  • Issue template committed to at least one repo
  • Built-in workflows enabled
  • Teams created, access granted
  • 5 real cards created (mix of issues + drafts) to test flow

Common Failure Modes (GitHub-Specific)

  • Multiple projects. Software team spins up Software Board. Kills cross-subteam visibility. One Project v2, many views.
  • Issues without project. Someone opens an issue but never adds it to the board. Fix with auto-add workflow (Section 9).
  • Drafts that stay drafts. Business items linger as drafts forever; nobody can link a PR. Convert to issue the moment ownership + scope are set.
  • Label drift. New labels invented per repo. Lead Mentor owns the label list; use gh label clone to sync.
  • PR merged, card stuck. PR did not use Closes #NNN / Fixes #NNN in the description. Enforce via PR template.
  • Board only used at stand-up. Same as Notion. If not source of truth during the work block, it is decoration.

Comments