{"id":1189,"date":"2026-09-26T05:17:20","date_gmt":"2026-09-26T05:17:20","guid":{"rendered":"https:\/\/www.devopsschool.com\/tutorials\/?p=1189"},"modified":"2026-09-26T05:17:23","modified_gmt":"2026-09-26T05:17:23","slug":"github-projects-complete-reference-guide-tutorial","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/tutorials\/github-projects-complete-reference-guide-tutorial\/","title":{"rendered":"GitHub Projects \u2014 Complete Reference Guide & Tutorial"},"content":{"rendered":"\n
\n

Scope:<\/strong> Current GitHub Projects \/ Projects v2<\/strong>, not Projects (classic).
Audience:<\/strong> Developers, DevOps engineers, engineering managers, product managers, project administrators, platform teams, and GitHub organization owners.
Last verified:<\/strong> 2026-09-26 against current GitHub documentation.
Learning style:<\/strong> Concept -> Why it matters -> Hands-on steps -> Example -> Operational guidance.<\/p>\n<\/blockquote>\n\n\n\n

\n\n\n\n

How to Use This Guide<\/h2>\n\n\n\n

This is both a tutorial<\/strong> and a reference manual<\/strong>. You can read it end-to-end, or jump directly to the section you need.<\/p>\n\n\n\n

    \n
  • Basic (1-2):<\/strong>\u00a0Understand what Projects is and create your first project.<\/li>\n\n\n\n
  • Fundamentals (3-5):<\/strong>\u00a0Learn items, fields, and GitHub metadata.<\/li>\n\n\n\n
  • Essentials (6-13):<\/strong>\u00a0Master views, tables, boards, roadmaps, filters, iterations, and status tracking.<\/li>\n\n\n\n
  • Intermediate (14-28):<\/strong>\u00a0Add workflows, insights, templates, permissions, documentation, linking, and planning patterns.<\/li>\n\n\n\n
  • Advanced (29-59):<\/strong>\u00a0Automate with Actions, APIs and CLI; design organization-scale operating models; secure and govern Projects.<\/li>\n\n\n\n
  • Complete Reference (60):<\/strong>\u00a0Use the final feature map as a revision\/checklist page.<\/li>\n<\/ul>\n\n\n\n

    Running Example Used Throughout<\/h3>\n\n\n\n

    Imagine an organization named acme-corp<\/code> with three repositories:<\/p>\n\n\n\n

    acme-corp\/web\nacme-corp\/api\nacme-corp\/infra\n<\/code><\/pre>\n\n\n\n
    The organization creates one organization-level project:<\/p>\n\n\n\n
    Acme Platform Delivery\n<\/code><\/pre>\n\n\n\n
    Recommended starter fields:<\/p>\n\n\n\n
    Field<\/th>Type<\/th>Example values<\/th>Purpose<\/th><\/tr><\/thead>
    Status<\/td>Single select<\/td>Todo, In Progress, In Review, Done<\/td>Workflow state<\/td><\/tr>
    Priority<\/td>Single select<\/td>P0, P1, P2, P3<\/td>Business\/technical priority<\/td><\/tr>
    Sprint<\/td>Iteration<\/td>Sprint 24, Sprint 25<\/td>Time-boxed planning<\/td><\/tr>
    Estimate<\/td>Number<\/td>1, 2, 3, 5, 8<\/td>Capacity planning<\/td><\/tr>
    Team<\/td>Single select<\/td>Web, API, Platform<\/td>Ownership<\/td><\/tr>
    Start date<\/td>Date<\/td>2026-10-01<\/td>Roadmap start<\/td><\/tr>
    Target date<\/td>Date<\/td>2026-10-15<\/td>Roadmap target<\/td><\/tr>
    Release<\/td>Text or single select<\/td>2026.10<\/td>Release grouping<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    The Mental Model<\/h3>\n\n\n\n
    flowchart LR\n    A[Repositories] --> B[Issues and Pull Requests]\n    B --> C[GitHub Project]\n    D[Draft Issues] --> C\n    C --> E[Fields]\n    C --> F[Views]\n    C --> G[Workflows]\n    C --> H[Insights]\n    F --> I[Table]\n    F --> J[Board]\n    F --> K[Roadmap]\n    G --> L[Built-in Automation]\n    G --> M[Actions and APIs]\n<\/code><\/pre>\n\n\n\n
    The key idea is simple: Projects does not replace issues and pull requests. It organizes and enriches them for planning.<\/strong><\/p>\n\n\n\n
    \n\n\n\n
    Part I \u2014 BASIC<\/h1>\n\n\n\n
    1. BASIC \u2014 GitHub Projects Foundations<\/h1>\n\n\n\n
    1.1 Introduction to GitHub Projects<\/h2>\n\n\n\n
    GitHub Projects is GitHub’s flexible planning and work-tracking system. A project can contain issues, pull requests, and draft issues<\/strong>, then add planning metadata and multiple views without duplicating the underlying work.<\/p>\n\n\n\n
    A useful way to distinguish GitHub’s planning primitives is:<\/p>\n\n\n\n
    Tool<\/th>Primary purpose<\/th>Best use<\/th><\/tr><\/thead>
    Issue<\/td>Track a unit of work, problem, request, or decision<\/td>Bug, feature, task, incident action<\/td><\/tr>
    Pull request<\/td>Review and merge code changes<\/td>Implementation and review<\/td><\/tr>
    Milestone<\/td>Group issues\/PRs toward a repository-level target<\/td>Release or phase<\/td><\/tr>
    Project<\/td>Plan and visualize many work items with fields\/views<\/td>Backlog, sprint, roadmap, portfolio<\/td><\/tr>
    Project update<\/td>Communicate project-level health<\/td>Executive\/status communication<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Projects vs Issues<\/h3>\n\n\n\n
    An issue<\/strong> represents work. A project<\/strong> represents a planning context around work.<\/p>\n\n\n\n
    One issue can appear in multiple projects. Each project can add its own project-scoped field values. This is useful when, for example, the engineering project tracks Sprint<\/code> while a company-wide project tracks Strategic initiative<\/code>.<\/p>\n\n\n\n
    Projects vs Pull Requests<\/h3>\n\n\n\n
    Pull requests are code-review objects. Projects can include PRs directly and can also expose PR-related metadata such as reviewers and linked pull requests. A mature delivery project often tracks both the issue describing the work and the PR implementing it.<\/p>\n\n\n\n
    Projects vs Milestones<\/h3>\n\n\n\n
    Milestones are comparatively lightweight and repository-oriented. Projects are richer and can span repositories. Use milestones for a release grouping when that model fits; use Projects for multidimensional planning, custom fields, multiple layouts, charts, and automation.<\/p>\n\n\n\n
    Projects vs Projects (classic)<\/h3>\n\n\n\n
    This guide covers current Projects<\/strong>, historically called Projects v2<\/strong>. Avoid learning workflows that depend on classic project-board columns\/cards. Current Projects is field-driven: the same underlying data can be rendered as a table, board, or roadmap.<\/p>\n\n\n\n
    Common Planning Use Cases<\/h3>\n\n\n\n
    Use case<\/th>Recommended view\/model<\/th><\/tr><\/thead>
    Product backlog<\/td>Table grouped\/sorted by Priority<\/td><\/tr>
    Sprint planning<\/td>Iteration field + Board<\/td><\/tr>
    Kanban<\/td>Board using Status as columns<\/td><\/tr>
    Product roadmap<\/td>Roadmap using date\/iteration fields<\/td><\/tr>
    Cross-repository delivery<\/td>Organization project + Repository field<\/td><\/tr>
    Team capacity<\/td>Iteration + Estimate + Team\/Assignee grouping<\/td><\/tr>
    Executive overview<\/td>Roadmap + project updates + insights<\/td><\/tr>
    Release tracking<\/td>Milestone\/Release field + filtered saved view<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    1.2 GitHub Projects Core Concepts<\/h2>\n\n\n\n
    Concept<\/th>Meaning<\/th><\/tr><\/thead>
    Project<\/td>Planning container owned by a user or organization<\/td><\/tr>
    Project item<\/td>A row\/card\/timeline item inside the project<\/td><\/tr>
    Issue<\/td>Repository work item<\/td><\/tr>
    Pull request<\/td>Repository code-change\/review item<\/td><\/tr>
    Draft issue<\/td>Project-local idea that can later become an issue<\/td><\/tr>
    Field<\/td>Metadata exposed in the project<\/td><\/tr>
    Custom field<\/td>Project-defined text\/number\/date\/single-select\/iteration metadata<\/td><\/tr>
    GitHub metadata<\/td>Native data such as Assignees, Labels, Milestone, Repository<\/td><\/tr>
    View<\/td>Saved presentation\/configuration of project data<\/td><\/tr>
    Table<\/td>Spreadsheet-style layout<\/td><\/tr>
    Board<\/td>Column\/card layout<\/td><\/tr>
    Roadmap<\/td>Timeline layout<\/td><\/tr>
    Workflow<\/td>Automation that reacts to project\/item events<\/td><\/tr>
    Insight<\/td>Chart based on project data<\/td><\/tr>
    Template<\/td>Reusable project configuration<\/td><\/tr>
    Project update<\/td>Project-level health\/date\/message update<\/td><\/tr>
    Access<\/td>Read\/write\/admin permissions<\/td><\/tr>
    Visibility<\/td>Public or private discoverability<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Important Principle: Data vs View<\/h3>\n\n\n\n
    flowchart TD\n    A[Project Data] --> B[Items]\n    A --> C[Fields]\n    B --> D[Saved View 1: Backlog Table]\n    B --> E[Saved View 2: Sprint Board]\n    B --> F[Saved View 3: Roadmap]\n    C --> D\n    C --> E\n    C --> F\n<\/code><\/pre>\n\n\n\n
    A view does not<\/strong> normally create a second copy of the work. It is another lens over the same project items and fields.<\/p>\n\n\n\n
    1.3 Project Ownership<\/h2>\n\n\n\n
    Projects can be owned by a personal account<\/strong> or an organization<\/strong>.<\/p>\n\n\n\n
    User-Owned Projects<\/h3>\n\n\n\n
    Useful for personal planning, prototypes, individual work, or repositories owned by your personal account.<\/p>\n\n\n\n
    Organization-Owned Projects<\/h3>\n\n\n\n
    Best for shared engineering\/product work because they support organization collaboration, teams, organization templates, base permissions, cross-repository planning, and governance.<\/p>\n\n\n\n
    Recommendation<\/h3>\n\n\n\n
    For company\/team work, prefer organization-owned projects<\/strong> unless there is a specific reason to use a personal project.<\/p>\n\n\n\n
    1.4 Finding Projects<\/h2>\n\n\n\n
    Projects can surface from several places:<\/p>\n\n\n\n
      \n
    • Your profile’s\u00a0Projects<\/strong>\u00a0page.<\/li>\n\n\n\n
    • An organization’s\u00a0Projects<\/strong>\u00a0page.<\/li>\n\n\n\n
    • A repository’s\u00a0Projects<\/strong>\u00a0tab when a project is linked\/defaulted there.<\/li>\n\n\n\n
    • A team’s\u00a0Projects<\/strong>\u00a0page when linked to the team.<\/li>\n\n\n\n
    • Project search\/discovery pages and recent-project navigation.<\/li>\n\n\n\n
    • Direct project URLs.<\/li>\n<\/ul>\n\n\n\n
      For an organization-level project, a typical URL is:<\/p>\n\n\n\n
      https://github.com\/orgs\/acme-corp\/projects\/12\n<\/code><\/pre>\n\n\n\n
      The final number (12<\/code>) is the project number<\/strong>, which is different from the GraphQL node ID.<\/p>\n\n\n\n
      \n\n\n\n
      2. BASIC \u2014 Creating Projects<\/h1>\n\n\n\n
      2.1 Project Creation<\/h2>\n\n\n\n
      You can start with a blank Table<\/strong>, Board<\/strong>, or Roadmap<\/strong>, or use a template.<\/p>\n\n\n\n
      Organization Project \u2014 UI Flow<\/h3>\n\n\n\n
      flowchart LR\n    A[Open Organization] --> B[Projects]\n    B --> C[New project]\n    C --> D{Choose source}\n    D -->|Blank| E[Table \/ Board \/ Roadmap]\n    D -->|Template| F[Built-in \/ Org \/ Recommended]\n    E --> G[Name project]\n    F --> G\n    G --> H[Optional repository import]\n    H --> I[Create project]\n<\/code><\/pre>\n\n\n\n
      Practical Steps<\/h3>\n\n\n\n
        \n
      1. Open the GitHub organization.<\/li>\n\n\n\n
      2. Select\u00a0Projects<\/strong>.<\/li>\n\n\n\n
      3. Click\u00a0New project<\/strong>.<\/li>\n\n\n\n
      4. Choose\u00a0Table<\/strong>,\u00a0Board<\/strong>,\u00a0Roadmap<\/strong>, or a template.<\/li>\n\n\n\n
      5. Give the project a clear name, for example\u00a0Acme Platform Delivery<\/code>.<\/li>\n\n\n\n
      6. Optionally import items from a repository.<\/li>\n\n\n\n
      7. Create the project.<\/li>\n\n\n\n
      8. Open project\u00a0Settings<\/strong>\u00a0and add a short description and README.<\/li>\n<\/ol>\n\n\n\n
        Good Naming Pattern<\/h3>\n\n\n\n
        <team\/product> \u2014 <planning purpose>\n<\/code><\/pre>\n\n\n\n
        Examples:<\/p>\n\n\n\n
        Platform \u2014 Delivery\nMobile \u2014 Q4 Roadmap\nSecurity \u2014 Remediation Program\nPayments \u2014 Sprint Planning\n<\/code><\/pre>\n\n\n\n
        Description vs README<\/h3>\n\n\n\n
          \n
        • Description:<\/strong>\u00a0one-sentence purpose.<\/li>\n\n\n\n
        • README:<\/strong>\u00a0operating instructions and conventions.<\/li>\n<\/ul>\n\n\n\n
          Example project README:<\/p>\n\n\n\n
          ## Purpose\nTrack delivery work across web, API, and infrastructure.\n\n## Working agreements\n- Every delivery item must have Status and Priority.\n- Sprint is assigned only after planning commitment.\n- P0\/P1 items require an owner.\n- Done items are automatically archived after the retention period.\n\n## Views\n- Backlog: prioritized uncommitted work\n- Current Sprint: execution board\n- Roadmap: delivery timeline\n- Risks: P0\/P1 work not Done\n<\/code><\/pre>\n\n\n\n
          2.2 Project Creation Sources<\/h2>\n\n\n\n
          Source<\/th>When to use<\/th><\/tr><\/thead>
          Blank Table<\/td>Start data-first; best default for setup<\/td><\/tr>
          Blank Board<\/td>Team already thinks in workflow columns<\/td><\/tr>
          Blank Roadmap<\/td>Timeline is the primary need<\/td><\/tr>
          Built-in template<\/td>Fast start for common planning patterns<\/td><\/tr>
          Organization template<\/td>Standardized internal workflow<\/td><\/tr>
          Recommended template<\/td>Organization-curated preferred starting point<\/td><\/tr>
          Existing project copy<\/td>Reuse a proven configuration<\/td><\/tr>
          Import from repository<\/td>Seed the project with existing issues\/PRs<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
          When importing items from a repository during project creation, GitHub can designate that repository as the project’s default repository<\/strong>. A default repository makes issue creation from the project faster because the destination repo is preselected.<\/p>\n\n\n\n
          2.3 Copying Projects<\/h2>\n\n\n\n
          Copying a project is useful for repeated releases, programs, client engagements, or team setups.<\/p>\n\n\n\n
          A copied project can carry forward configuration such as:<\/p>\n\n\n\n
            \n
          • Views.<\/li>\n\n\n\n
          • Custom fields.<\/li>\n\n\n\n
          • Draft issues and their field values if selected.<\/li>\n\n\n\n
          • Configured workflows, except auto-add workflows.<\/li>\n\n\n\n
          • Insights\/charts.<\/li>\n<\/ul>\n\n\n\n
            It does not<\/strong> simply clone all original work items and access relationships. Treat a copy as configuration reuse<\/strong>, not as a full project backup.<\/p>\n\n\n\n
            Copy vs Template<\/h3>\n\n\n\n
            Need<\/th>Prefer<\/th><\/tr><\/thead>
            One-off clone of a working setup<\/td>Copy project<\/td><\/tr>
            Organization-wide standard<\/td>Organization template<\/td><\/tr>
            Curated creation experience<\/td>Recommended template<\/td><\/tr>
            Versioned operating standard<\/td>Maintained template + documented change process<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
            \n\n\n\n
            Part II \u2014 FUNDAMENTALS<\/h1>\n\n\n\n
            3. FUNDAMENTALS \u2014 Project Items<\/h1>\n\n\n\n
            3.1 Item Types<\/h2>\n\n\n\n
            Projects work with three main item types:<\/p>\n\n\n\n
              \n
            1. Issues<\/strong>\u00a0\u2014 real repository work items.<\/li>\n\n\n\n
            2. Pull requests<\/strong>\u00a0\u2014 code changes\/reviews.<\/li>\n\n\n\n
            3. Draft issues<\/strong>\u00a0\u2014 project-local ideas\/notes that can later be converted.<\/li>\n<\/ol>\n\n\n\n
              Choosing the Right Item Type<\/h3>\n\n\n\n
              Situation<\/th>Use<\/th><\/tr><\/thead>
              Work must be discussed, assigned, linked, searched in a repo<\/td>Issue<\/td><\/tr>
              Code change is the planning object<\/td>Pull request<\/td><\/tr>
              Idea is not ready for a repository yet<\/td>Draft issue<\/td><\/tr>
              Backlog brainstorming session<\/td>Draft issue first, convert later<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
              3.2 Adding Items<\/h2>\n\n\n\n
              You can add work in several ways.<\/p>\n\n\n\n
              A. Search from the Project<\/h3>\n\n\n\n
              In the project’s add-item row, type #<\/code> and choose a repository, then search for an issue or PR.<\/p>\n\n\n\n
              B. Paste a URL<\/h3>\n\n\n\n
              Paste an issue\/PR URL into the add-item row:<\/p>\n\n\n\n
              https://github.com\/acme-corp\/api\/issues\/418\n<\/code><\/pre>\n\n\n\n
              C. Add from Repository<\/h3>\n\n\n\n
              Use Add item from repository<\/strong>, select multiple items, and add them in bulk.<\/p>\n\n\n\n
              D. Add from the Repository Issue\/PR List<\/h3>\n\n\n\n
              Select several issues or PRs -> Projects<\/strong> -> choose the destination project.<\/p>\n\n\n\n
              E. Add from Inside an Issue or PR<\/h3>\n\n\n\n
              Open the issue\/PR -> Projects<\/strong> in the sidebar -> select the project -> optionally populate project fields.<\/p>\n\n\n\n
              F. Command Palette<\/h3>\n\n\n\n
              On macOS:<\/p>\n\n\n\n
              Command + K\n<\/code><\/pre>\n\n\n\n
              On Windows\/Linux:<\/p>\n\n\n\n
              Ctrl + K\n<\/code><\/pre>\n\n\n\n
              Search for Add items<\/strong>.<\/p>\n\n\n\n
              G. Automatic Addition<\/h3>\n\n\n\n
              Configure the built-in Auto-add to project<\/strong> workflow. We cover this deeply in Chapter 15.<\/p>\n\n\n\n
              3.3 Draft Issues<\/h2>\n\n\n\n
              Draft issues are excellent for planning workshops because they let you capture an idea without immediately choosing a repository.<\/p>\n\n\n\n
              Example draft:<\/p>\n\n\n\n
              Title: Add regional failover runbook\nBody: Define RTO\/RPO, traffic cutover, database recovery, and rollback steps.\n<\/code><\/pre>\n\n\n\n
              Typical lifecycle:<\/p>\n\n\n\n
              flowchart LR\n    A[Idea] --> B[Draft Issue]\n    B --> C[Refine title\/body]\n    C --> D[Assign project fields]\n    D --> E{Ready for engineering?}\n    E -->|No| C\n    E -->|Yes| F[Convert to Issue]\n    F --> G[Choose repository]\n<\/code><\/pre>\n\n\n\n
              When converting a draft issue, choose the repository that should own the resulting issue. After conversion, the item becomes a normal GitHub issue while staying represented in the project.<\/p>\n\n\n\n
              3.4 Creating Issues from Projects<\/h2>\n\n\n\n
              Projects can create repository issues without leaving the planning context.<\/p>\n\n\n\n
                \n
              1. Click the add control at the bottom of a table\/group\/board column.<\/li>\n\n\n\n
              2. Choose\u00a0Create new issue<\/strong>.<\/li>\n\n\n\n
              3. Select the destination repository.<\/li>\n\n\n\n
              4. Enter title\/body and available metadata.<\/li>\n\n\n\n
              5. Create the issue.<\/li>\n<\/ol>\n\n\n\n
                A useful behavior: when creating an issue inside a grouped view, the group’s value can be applied automatically. For example, creating in the In Progress<\/code> group can prepopulate the project’s Status as In Progress<\/code>.<\/p>\n\n\n\n
                3.5 Editing Items<\/h2>\n\n\n\n
                Projects is designed for high-volume editing.<\/p>\n\n\n\n
                Inline Editing<\/h3>\n\n\n\n
                Click field cells directly and change values.<\/p>\n\n\n\n
                Bulk Editing<\/h3>\n\n\n\n
                Select multiple rows\/cards, then apply a shared field value or action.<\/p>\n\n\n\n
                Drag-and-Drop Editing<\/h3>\n\n\n\n
                When grouped by a field, dragging an item to another group changes that field value.<\/p>\n\n\n\n
                Example:<\/p>\n\n\n\n
                Group by: Priority\nMove issue from P2 group -> P1 group\nResult: Priority becomes P1\n<\/code><\/pre>\n\n\n\n
                This makes the view itself an editing interface.<\/p>\n\n\n\n
                3.6 Archiving Items<\/h2>\n\n\n\n
                Archive<\/strong> removes an item from normal project views while preserving its project context and custom-field data. Delete\/remove<\/strong> permanently removes the project item from the project.<\/p>\n\n\n\n
                Action<\/th>Still visible in project views?<\/th>Recoverable?<\/th>Field context retained?<\/th><\/tr><\/thead>
                Archive<\/td>No<\/td>Yes, restore<\/td>Yes<\/td><\/tr>
                Restore<\/td>Yes<\/td>N\/A<\/td>Yes<\/td><\/tr>
                Delete\/remove item<\/td>No<\/td>No project restoration<\/td>No project membership<\/td><\/tr>
                Close underlying issue<\/td>Depends on view\/filter<\/td>Issue can be reopened<\/td>Project item remains unless archived\/removed<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                Use archiving as routine cleanup; reserve deletion for mistakes, duplicates, or true removal.<\/p>\n\n\n\n
                \n\n\n\n
                4. FUNDAMENTALS \u2014 Project Fields<\/h1>\n\n\n\n
                4.1 Field Fundamentals<\/h2>\n\n\n\n
                Fields add structured planning metadata to project items.<\/p>\n\n\n\n
                There are two broad classes:<\/p>\n\n\n\n
                  \n
                1. GitHub-provided metadata<\/strong>\u00a0such as Assignees, Labels, Milestone, Repository, Type, Parent issue, Reviewers.<\/li>\n\n\n\n
                2. Custom project fields<\/strong>\u00a0you create for your planning model.<\/li>\n<\/ol>\n\n\n\n
                  Current project custom-field types covered here are:<\/p>\n\n\n\n
                    \n
                  • Text.<\/li>\n\n\n\n
                  • Number.<\/li>\n\n\n\n
                  • Date.<\/li>\n\n\n\n
                  • Single select.<\/li>\n\n\n\n
                  • Iteration.<\/li>\n<\/ul>\n\n\n\n
                    Field Design Rule<\/h3>\n\n\n\n
                    Create a field only when you plan to filter, sort, group, slice, aggregate, automate, or report on it<\/strong>. If it is merely explanatory prose, it may belong in the issue body instead.<\/p>\n\n\n\n
                    4.2 Text Fields<\/h2>\n\n\n\n
                    Text fields hold free-form metadata.<\/p>\n\n\n\n
                    Good uses:<\/p>\n\n\n\n
                      \n
                    • External ticket ID.<\/li>\n\n\n\n
                    • Release train identifier.<\/li>\n\n\n\n
                    • Customer\/account reference.<\/li>\n\n\n\n
                    • Short planning note.<\/li>\n<\/ul>\n\n\n\n
                      Bad uses:<\/p>\n\n\n\n
                        \n
                      • Priority (single select<\/code>\u00a0is better).<\/li>\n\n\n\n
                      • Estimate (number<\/code>\u00a0is better).<\/li>\n\n\n\n
                      • Target date (date<\/code>\u00a0is better).<\/li>\n<\/ul>\n\n\n\n
                        Example:<\/p>\n\n\n\n
                        Field: External ID\nValue: INC-2026-00491\n<\/code><\/pre>\n\n\n\n
                        4.3 Number Fields<\/h2>\n\n\n\n
                        Number fields support numeric planning and aggregation.<\/p>\n\n\n\n
                        Examples:<\/p>\n\n\n\n
                        Estimate = 5\nCost = 1200\nRisk score = 8\nExpected hours = 16\n<\/code><\/pre>\n\n\n\n
                        Useful capabilities include numeric filtering and field sums.<\/p>\n\n\n\n
                        Example filters:<\/p>\n\n\n\n
                        estimate:>=5\nestimate:1..3\nestimate:*..8\n<\/code><\/pre>\n\n\n\n
                        Use one estimation scale consistently. Mixing hours and story points in the same field destroys the meaning of totals.<\/p>\n\n\n\n
                        4.4 Date Fields<\/h2>\n\n\n\n
                        Date fields enable deadline and roadmap behavior.<\/p>\n\n\n\n
                        Typical fields:<\/p>\n\n\n\n
                        Start date\nTarget date\nDue date\nRelease date\n<\/code><\/pre>\n\n\n\n
                        Example filters:<\/p>\n\n\n\n
                        target-date:@today\ntarget-date:>=@today\ntarget-date:@today..@today+7\n<\/code><\/pre>\n\n\n\n
                        Avoid creating several fields that mean almost the same thing. Define exactly what each date means in the README.<\/p>\n\n\n\n
                        4.5 Single-Select Fields<\/h2>\n\n\n\n
                        Single-select fields are excellent for taxonomies.<\/p>\n\n\n\n
                        Example Priority<\/code>:<\/p>\n\n\n\n
                        Option<\/th>Meaning<\/th><\/tr><\/thead>
                        P0<\/td>Immediate \/ critical<\/td><\/tr>
                        P1<\/td>High priority<\/td><\/tr>
                        P2<\/td>Normal planned work<\/td><\/tr>
                        P3<\/td>Lower priority \/ opportunistic<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                        Other common fields:<\/p>\n\n\n\n
                          \n
                        • Team.<\/li>\n\n\n\n
                        • Severity.<\/li>\n\n\n\n
                        • Workstream.<\/li>\n\n\n\n
                        • Product area.<\/li>\n\n\n\n
                        • Release readiness.<\/li>\n<\/ul>\n\n\n\n
                          Single-select options can have names, colors, and descriptions. The description should define semantics, not restate the label.<\/p>\n\n\n\n
                          4.6 Iteration Fields<\/h2>\n\n\n\n
                          Iteration fields represent repeating planning intervals such as sprints.<\/p>\n\n\n\n
                          Example:<\/p>\n\n\n\n
                          Sprint 24: 2026-09-21 to 2026-10-04\nSprint 25: 2026-10-05 to 2026-10-18\n<\/code><\/pre>\n\n\n\n
                          You configure:<\/p>\n\n\n\n
                            \n
                          • Start date.<\/li>\n\n\n\n
                          • Duration in days or weeks.<\/li>\n\n\n\n
                          • Naming.<\/li>\n\n\n\n
                          • Future iterations.<\/li>\n\n\n\n
                          • Optional breaks.<\/li>\n<\/ul>\n\n\n\n
                            Relative filters make iteration fields especially powerful:<\/p>\n\n\n\n
                            sprint:@previous\nsprint:@current\nsprint:@next\nsprint:@current..@current+3\n<\/code><\/pre>\n\n\n\n
                            Why Iteration Is Better Than a Free-Text Sprint Field<\/h3>\n\n\n\n
                            An iteration understands chronology. GitHub can reason about previous\/current\/next and display iterations on roadmaps. A text field cannot.<\/p>\n\n\n\n
                            4.7 Managing Custom Fields<\/h2>\n\n\n\n
                            Typical field lifecycle:<\/p>\n\n\n\n
                            flowchart LR\n    A[Need identified] --> B[Choose field type]\n    B --> C[Create field]\n    C --> D[Define semantics]\n    D --> E[Use in views\/workflows]\n    E --> F[Review usage]\n    F --> G{Still useful?}\n    G -->|Yes| E\n    G -->|No| H[Remove\/Delete carefully]\n<\/code><\/pre>\n\n\n\n
                            Before renaming or deleting a field:<\/p>\n\n\n\n
                              \n
                            • Check saved views.<\/li>\n\n\n\n
                            • Check automation\/API scripts.<\/li>\n\n\n\n
                            • Check charts.<\/li>\n\n\n\n
                            • Check team documentation.<\/li>\n\n\n\n
                            • Check whether a similar organization-level issue field should replace it.<\/li>\n<\/ul>\n\n\n\n
                              \n\n\n\n
                              5. FUNDAMENTALS \u2014 GitHub Metadata Fields<\/h1>\n\n\n\n
                              5.1 Issue and Pull Request Metadata<\/h2>\n\n\n\n
                              Projects can display native GitHub metadata such as:<\/p>\n\n\n\n
                                \n
                              • Title.<\/li>\n\n\n\n
                              • Assignees.<\/li>\n\n\n\n
                              • Labels.<\/li>\n\n\n\n
                              • Milestone.<\/li>\n\n\n\n
                              • Repository.<\/li>\n\n\n\n
                              • Status (project field).<\/li>\n\n\n\n
                              • Issue\/PR state.<\/li>\n<\/ul>\n\n\n\n
                                Understand the difference between native metadata<\/strong> and project metadata<\/strong>. A repository label is attached to the issue itself; a project custom field is normally scoped to that project.<\/p>\n\n\n\n
                                5.2 Issue Type<\/h2>\n\n\n\n
                                Organizations can use issue types to classify issues. GitHub provides default types such as:<\/p>\n\n\n\n
                                Bug\nTask\nFeature\n<\/code><\/pre>\n\n\n\n
                                Organizations can customize issue types. The project can expose a Type<\/strong> field and use it in views\/filters.<\/p>\n\n\n\n
                                Example:<\/p>\n\n\n\n
                                type:bug status:\"In Progress\"\n<\/code><\/pre>\n\n\n\n
                                Use issue types for stable semantic categories; do not recreate Bug<\/code>, Task<\/code>, and Feature<\/code> as ordinary project single-select values unless you have a specific migration reason.<\/p>\n\n\n\n
                                5.3 Parent and Sub-Issue Fields<\/h2>\n\n\n\n
                                GitHub issue hierarchy can be exposed in Projects through:<\/p>\n\n\n\n
                                  \n
                                • Parent issue<\/strong>.<\/li>\n\n\n\n
                                • Sub-issue progress<\/strong>.<\/li>\n<\/ul>\n\n\n\n
                                  Example filter:<\/p>\n\n\n\n
                                  parent-issue:acme-corp\/api#418\n<\/code><\/pre>\n\n\n\n
                                  This is useful for work breakdown:<\/p>\n\n\n\n
                                  flowchart TD\n    A[Initiative Issue] --> B[Feature Issue]\n    A --> C[Feature Issue]\n    B --> D[Task]\n    B --> E[Task]\n    C --> F[Task]\n<\/code><\/pre>\n\n\n\n
                                  Do not invent hierarchy purely with text prefixes like [EPIC]<\/code>. Prefer real parent\/sub-issue relationships plus issue types where possible.<\/p>\n\n\n\n
                                  5.4 Pull Request Fields<\/h2>\n\n\n\n
                                  Useful PR-related fields include:<\/p>\n\n\n\n
                                    \n
                                  • Linked pull requests.<\/li>\n\n\n\n
                                  • Reviewers.<\/li>\n\n\n\n
                                  • Pull request state.<\/li>\n\n\n\n
                                  • Merge\/closed status through native PR state.<\/li>\n<\/ul>\n\n\n\n
                                    A delivery view can therefore show:<\/p>\n\n\n\n
                                    Issue -> Linked PR -> Reviewer -> Status\n<\/code><\/pre>\n\n\n\n
                                    This is valuable for identifying work that is “implemented but waiting for review.”<\/p>\n\n\n\n
                                    5.5 Organization-Level Issue Fields<\/h2>\n\n\n\n
                                    Organization-level issue fields<\/strong> provide structured metadata that lives on the issue and remains consistent across projects in the organization. Current issue-field types include text, number, date, and single-select.<\/p>\n\n\n\n
                                    This is different from a project custom field:<\/p>\n\n\n\n
                                    Characteristic<\/th>Organization issue field<\/th>Project custom field<\/th><\/tr><\/thead>
                                    Scope<\/td>Organization issues<\/td>One project<\/td><\/tr>
                                    Value follows issue across projects<\/td>Yes<\/td>No<\/td><\/tr>
                                    Good for shared Priority\/Effort<\/td>Yes<\/td>Sometimes<\/td><\/tr>
                                    Applies to PRs<\/td>No<\/td>Project fields can apply to project items generally<\/td><\/tr>
                                    Governance owner<\/td>Organization<\/td>Project admins<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                    Example Architecture<\/h3>\n\n\n\n
                                    Use organization issue fields for metadata that should be globally consistent:<\/p>\n\n\n\n
                                    Priority\nEffort\nStart date\nTarget date\n<\/code><\/pre>\n\n\n\n
                                    Use project-only fields for planning context that legitimately differs by project:<\/p>\n\n\n\n
                                    Program wave\nPortfolio lane\nLocal delivery confidence\n<\/code><\/pre>\n\n\n\n
                                    Avoid having two fields named Priority<\/code> with different meanings.<\/p>\n\n\n\n
                                    \n\n\n\n
                                    Part III \u2014 ESSENTIALS<\/h1>\n\n\n\n
                                    6. ESSENTIALS \u2014 Project Views<\/h1>\n\n\n\n
                                    6.1 View Fundamentals<\/h2>\n\n\n\n
                                    A project can have multiple saved views. Each view can have its own:<\/p>\n\n\n\n
                                      \n
                                    • Layout.<\/li>\n\n\n\n
                                    • Filter.<\/li>\n\n\n\n
                                    • Sort.<\/li>\n\n\n\n
                                    • Grouping.<\/li>\n\n\n\n
                                    • Slicing.<\/li>\n\n\n\n
                                    • Visible fields.<\/li>\n\n\n\n
                                    • Board column configuration.<\/li>\n\n\n\n
                                    • Roadmap dates\/markers.<\/li>\n<\/ul>\n\n\n\n
                                      Example view set:<\/p>\n\n\n\n
                                      View<\/th>Layout<\/th>Purpose<\/th><\/tr><\/thead>
                                      Backlog<\/td>Table<\/td>Prioritize uncommitted work<\/td><\/tr>
                                      Current Sprint<\/td>Board<\/td>Daily execution<\/td><\/tr>
                                      My Work<\/td>Table<\/td>Personal workload<\/td><\/tr>
                                      Roadmap<\/td>Roadmap<\/td>Timeline planning<\/td><\/tr>
                                      Risks<\/td>Table<\/td>High-risk incomplete work<\/td><\/tr>
                                      Done<\/td>Table<\/td>Recently completed work<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                      6.2 Managing Views<\/h2>\n\n\n\n
                                      Common actions:<\/p>\n\n\n\n
                                        \n
                                      • Create.<\/li>\n\n\n\n
                                      • Duplicate.<\/li>\n\n\n\n
                                      • Rename.<\/li>\n\n\n\n
                                      • Save changes.<\/li>\n\n\n\n
                                      • Reorder tabs.<\/li>\n\n\n\n
                                      • Delete.<\/li>\n\n\n\n
                                      • Share the view URL.<\/li>\n<\/ul>\n\n\n\n
                                        Saved vs Unsaved Changes<\/h3>\n\n\n\n
                                        When you change a saved view’s filter\/sort\/grouping, GitHub may mark the view as modified. Save the changes if the configuration should become the shared default.<\/p>\n\n\n\n
                                        A useful discipline is:<\/p>\n\n\n\n
                                        Exploration = do not save\nTeam convention = save\n<\/code><\/pre>\n\n\n\n
                                        6.3 Switching Layouts<\/h2>\n\n\n\n
                                        The same project view can use:<\/p>\n\n\n\n
                                          \n
                                        • Table<\/strong>\u00a0\u2014 dense editing\/analysis.<\/li>\n\n\n\n
                                        • Board<\/strong>\u00a0\u2014 workflow\/card movement.<\/li>\n\n\n\n
                                        • Roadmap<\/strong>\u00a0\u2014 timeline\/date planning.<\/li>\n<\/ul>\n\n\n\n
                                          Each saved view is independently configured. You do not need separate projects just to get separate layouts.<\/p>\n\n\n\n
                                          \n\n\n\n
                                          7. ESSENTIALS \u2014 Table Layout<\/h1>\n\n\n\n
                                          7.1 Table Fundamentals<\/h2>\n\n\n\n
                                          The table is the best place to configure and edit structured project data because it exposes rows and columns directly.<\/p>\n\n\n\n
                                          Use it for:<\/p>\n\n\n\n
                                            \n
                                          • Backlog grooming.<\/li>\n\n\n\n
                                          • Bulk metadata cleanup.<\/li>\n\n\n\n
                                          • Planning workshops.<\/li>\n\n\n\n
                                          • Capacity analysis.<\/li>\n\n\n\n
                                          • Audit\/review of fields.<\/li>\n<\/ul>\n\n\n\n
                                            7.2 Table Customization<\/h2>\n\n\n\n
                                            You can show\/hide and reorder fields to make each table fit its audience.<\/p>\n\n\n\n
                                            Engineering table example:<\/p>\n\n\n\n
                                            Title | Status | Assignees | Priority | Sprint | Estimate | Linked PRs\n<\/code><\/pre>\n\n\n\n
                                            Leadership table example:<\/p>\n\n\n\n
                                            Title | Status | Team | Priority | Target date | Milestone\n<\/code><\/pre>\n\n\n\n
                                            The underlying project remains the same; only the visible representation changes.<\/p>\n\n\n\n
                                            7.3 Table Organization<\/h2>\n\n\n\n
                                            Group<\/h3>\n\n\n\n
                                            Example:<\/p>\n\n\n\n
                                            Group by: Priority\n<\/code><\/pre>\n\n\n\n
                                            This creates sections such as P0, P1, P2, P3.<\/p>\n\n\n\n
                                            Sort<\/h3>\n\n\n\n
                                            Example:<\/p>\n\n\n\n
                                            Sort 1: Priority ascending\nSort 2: Target date ascending\n<\/code><\/pre>\n\n\n\n
                                            Slice<\/h3>\n\n\n\n
                                            Slicing opens a value selector that lets you quickly focus on one value at a time, such as Team or Sprint, without permanently rebuilding the view.<\/p>\n\n\n\n
                                            Field Sums<\/h3>\n\n\n\n
                                            For a numeric Estimate<\/code> field, show sums per group to see capacity.<\/p>\n\n\n\n
                                            Example:<\/p>\n\n\n\n
                                            Sprint 24\n  API: 22 points\n  Web: 18 points\n  Platform: 13 points\n<\/code><\/pre>\n\n\n\n
                                            7.4 Table Editing<\/h2>\n\n\n\n
                                            Dragging an item between groups updates the grouped field. Bulk selection makes table layout especially effective for backlog normalization.<\/p>\n\n\n\n
                                            Example cleanup workflow:<\/p>\n\n\n\n
                                              \n
                                            1. Filter\u00a0no:priority<\/code>.<\/li>\n\n\n\n
                                            2. Select related items.<\/li>\n\n\n\n
                                            3. Bulk-set Priority.<\/li>\n\n\n\n
                                            4. Filter\u00a0no:assignee<\/code>.<\/li>\n\n\n\n
                                            5. Assign owners.<\/li>\n\n\n\n
                                            6. Save a\u00a0Triage<\/code>\u00a0view if this is a recurring process.<\/li>\n<\/ol>\n\n\n\n
                                              \n\n\n\n
                                              8. ESSENTIALS \u2014 Board Layout<\/h1>\n\n\n\n
                                              8.1 Board Fundamentals<\/h2>\n\n\n\n
                                              Board layout represents items as cards arranged into columns.<\/p>\n\n\n\n
                                              Common Kanban board:<\/p>\n\n\n\n
                                              Todo -> In Progress -> In Review -> Done\n<\/code><\/pre>\n\n\n\n
                                              flowchart LR\n    A[Todo] --> B[In Progress]\n    B --> C[In Review]\n    C --> D[Done]\n<\/code><\/pre>\n\n\n\n
                                              8.2 Board Column Fields<\/h2>\n\n\n\n
                                              A board’s columns can be based on an appropriate field such as:<\/p>\n\n\n\n
                                                \n
                                              • Status.<\/li>\n\n\n\n
                                              • Single-select field.<\/li>\n\n\n\n
                                              • Iteration field.<\/li>\n<\/ul>\n\n\n\n
                                                That means a board does not have to represent workflow state. It can represent releases, teams, or iterations.<\/p>\n\n\n\n
                                                8.3 Board Configuration<\/h2>\n\n\n\n
                                                Useful controls:<\/p>\n\n\n\n
                                                  \n
                                                • Choose the column field.<\/li>\n\n\n\n
                                                • Show\/hide columns.<\/li>\n\n\n\n
                                                • Reorder cards.<\/li>\n\n\n\n
                                                • Move one or multiple cards.<\/li>\n\n\n\n
                                                • Show selected fields on cards.<\/li>\n\n\n\n
                                                • Group horizontally for a swimlane-like effect.<\/li>\n<\/ul>\n\n\n\n
                                                  Example:<\/p>\n\n\n\n
                                                  Columns: Status\nHorizontal group: Team\n<\/code><\/pre>\n\n\n\n
                                                  This creates a team-by-status operating board.<\/p>\n\n\n\n
                                                  8.4 Board Limits<\/h2>\n\n\n\n
                                                  You can set a column item limit<\/strong> as a work-in-progress signal.<\/p>\n\n\n\n
                                                  Important: the limit is informational<\/strong>, not a hard enforcement mechanism. Users and automation can still add cards beyond the limit; the UI highlights that the limit has been exceeded.<\/p>\n\n\n\n
                                                  Example:<\/p>\n\n\n\n
                                                  In Progress limit = 5\nCurrent count = 8  -> operational warning\n<\/code><\/pre>\n\n\n\n
                                                  8.5 Board Organization<\/h2>\n\n\n\n
                                                  You can combine:<\/p>\n\n\n\n
                                                    \n
                                                  • Filter.<\/li>\n\n\n\n
                                                  • Sort.<\/li>\n\n\n\n
                                                  • Slice.<\/li>\n\n\n\n
                                                  • Horizontal grouping.<\/li>\n\n\n\n
                                                  • Field sums.<\/li>\n\n\n\n
                                                  • Item counts.<\/li>\n<\/ul>\n\n\n\n
                                                    Example sprint board:<\/p>\n\n\n\n
                                                    Filter: sprint:@current\nColumns: Status\nGroup by: Team\nField sum: Estimate\n<\/code><\/pre>\n\n\n\n
                                                    8.6 Board Field Updates<\/h2>\n\n\n\n
                                                    Dragging cards is not merely visual. When the board is driven by Status, Iteration, or another supported column field, moving the card updates that field.<\/p>\n\n\n\n
                                                    This lets teams operate directly from the board during standups.<\/p>\n\n\n\n
                                                    \n\n\n\n
                                                    9. ESSENTIALS \u2014 Roadmap Layout<\/h1>\n\n\n\n
                                                    9.1 Roadmap Fundamentals<\/h2>\n\n\n\n
                                                    Roadmap layout places project items on a timeline using date or iteration fields.<\/p>\n\n\n\n
                                                    Use it for:<\/p>\n\n\n\n
                                                      \n
                                                    • Product roadmap.<\/li>\n\n\n\n
                                                    • Release planning.<\/li>\n\n\n\n
                                                    • Program sequencing.<\/li>\n\n\n\n
                                                    • Team delivery windows.<\/li>\n\n\n\n
                                                    • Quarterly\/annual visualization.<\/li>\n<\/ul>\n\n\n\n
                                                      9.2 Roadmap Dates<\/h2>\n\n\n\n
                                                      Choose the date or iteration fields used for start and target placement.<\/p>\n\n\n\n
                                                      Example:<\/p>\n\n\n\n
                                                      Start date field: Start date\nTarget date field: Target date\n<\/code><\/pre>\n\n\n\n
                                                      Dragging an item on the timeline can adjust these values, turning roadmap planning into an interactive editing process.<\/p>\n\n\n\n
                                                      9.3 Timeline Controls<\/h2>\n\n\n\n
                                                      Common zoom levels:<\/p>\n\n\n\n
                                                        \n
                                                      • Month.<\/li>\n\n\n\n
                                                      • Quarter.<\/li>\n\n\n\n
                                                      • Year.<\/li>\n<\/ul>\n\n\n\n
                                                        Use month for delivery planning, quarter for product\/program planning, and year for portfolio-level communication.<\/p>\n\n\n\n
                                                        9.4 Roadmap Markers<\/h2>\n\n\n\n
                                                        Markers can highlight important boundaries such as:<\/p>\n\n\n\n
                                                          \n
                                                        • Iterations.<\/li>\n\n\n\n
                                                        • Milestones.<\/li>\n\n\n\n
                                                        • Dates associated with items.<\/li>\n<\/ul>\n\n\n\n
                                                          Markers should represent shared reference points, not every minor date; too many markers make the roadmap unreadable.<\/p>\n\n\n\n
                                                          9.5 Roadmap Organization<\/h2>\n\n\n\n
                                                          Roadmap supports filtering, sorting, grouping, slicing, counts, and number-field sums.<\/p>\n\n\n\n
                                                          Example portfolio roadmap:<\/p>\n\n\n\n
                                                          Group by: Team\nFilter: -status:Done\nZoom: Quarter\nMarkers: Milestones\n<\/code><\/pre>\n\n\n\n
                                                          \n\n\n\n
                                                          10. ESSENTIALS \u2014 Filtering<\/h1>\n\n\n\n
                                                          Filtering is one of the most important GitHub Projects skills because good saved views are mostly good filters plus a suitable layout<\/strong>.<\/p>\n\n\n\n
                                                          10.1 Project Filters<\/h2>\n\n\n\n
                                                          Basic field filter:<\/p>\n\n\n\n
                                                          status:Done\n<\/code><\/pre>\n\n\n\n
                                                          Multiple fields use logical AND:<\/p>\n\n\n\n
                                                          label:bug status:\"In Progress\"\n<\/code><\/pre>\n\n\n\n
                                                          Multiple values for the same field can act like OR:<\/p>\n\n\n\n
                                                          label:bug,support\n<\/code><\/pre>\n\n\n\n
                                                          Negation uses -<\/code>:<\/p>\n\n\n\n
                                                          -status:Done\n<\/code><\/pre>\n\n\n\n
                                                          10.2 Value Filters<\/h2>\n\n\n\n
                                                          Has a value:<\/p>\n\n\n\n
                                                          has:assignee\nhas:priority\n<\/code><\/pre>\n\n\n\n
                                                          Missing a value:<\/p>\n\n\n\n
                                                          no:assignee\nno:priority\n<\/code><\/pre>\n\n\n\n
                                                          Require a value using negation of no:<\/code>:<\/p>\n\n\n\n
                                                          -no:priority\n<\/code><\/pre>\n\n\n\n
                                                          10.3 Item Filters<\/h2>\n\n\n\n
                                                          Examples:<\/p>\n\n\n\n
                                                          is:issue\nis:pr\nis:draft\nis:open\nis:closed\nis:merged\nis:issue is:open\n<\/code><\/pre>\n\n\n\n
                                                          Close reason examples:<\/p>\n\n\n\n
                                                          reason:completed\nreason:\"not planned\"\nreason:reopened\n<\/code><\/pre>\n\n\n\n
                                                          Updated-time examples:<\/p>\n\n\n\n
                                                          updated:@today\nupdated:@today-1d\nupdated:>@today-1w\n-updated:@today\n<\/code><\/pre>\n\n\n\n
                                                          10.4 Repository Filters<\/h2>\n\n\n\n
                                                          repo:acme-corp\/api\n<\/code><\/pre>\n\n\n\n
                                                          For cross-repository projects, repository filters are foundational for team-specific views.<\/p>\n\n\n\n
                                                          10.5 People Filters<\/h2>\n\n\n\n
                                                          assignee:octocat\nassignee:@me\nreviewers:octocat\n-reviewers:@me\n<\/code><\/pre>\n\n\n\n
                                                          10.6 Number Filters<\/h2>\n\n\n\n
                                                          estimate:>5\nestimate:>=5\nestimate:<8\nestimate:<=8\nestimate:1..5\nestimate:*..8\n<\/code><\/pre>\n\n\n\n
                                                          10.7 Date Filters<\/h2>\n\n\n\n
                                                          target-date:2026-10-15\ntarget-date:>=2026-10-01\ntarget-date:@today\ntarget-date:@today..@today+7\n<\/code><\/pre>\n\n\n\n
                                                          10.8 Iteration Filters<\/h2>\n\n\n\n
                                                          sprint:@previous\nsprint:@current\nsprint:@next\nsprint:<@current\nsprint:@current..@current+3\n<\/code><\/pre>\n\n\n\n
                                                          10.9 Text Filters<\/h2>\n\n\n\n
                                                          Exact field text:<\/p>\n\n\n\n
                                                          note:\"ready for release\"\n<\/code><\/pre>\n\n\n\n
                                                          General text search across titles\/text fields:<\/p>\n\n\n\n
                                                          API\n<\/code><\/pre>\n\n\n\n
                                                          Wildcard examples:<\/p>\n\n\n\n
                                                          title:API*\nlabel:*bug*\n<\/code><\/pre>\n\n\n\n
                                                          10.10 Relationship Filters<\/h2>\n\n\n\n
                                                          Issue type:<\/p>\n\n\n\n
                                                          type:bug\n<\/code><\/pre>\n\n\n\n
                                                          Parent issue:<\/p>\n\n\n\n
                                                          parent-issue:acme-corp\/api#418\n<\/code><\/pre>\n\n\n\n
                                                          Filter Recipes<\/h3>\n\n\n\n
                                                          Goal<\/th>Filter<\/th><\/tr><\/thead>
                                                          My open work<\/td>assignee:@me is:open<\/code><\/td><\/tr>
                                                          Current sprint<\/td>sprint:@current<\/code><\/td><\/tr>
                                                          Current sprint bugs<\/td>sprint:@current type:bug<\/code><\/td><\/tr>
                                                          Missing triage<\/td>no:assignee no:priority<\/code><\/td><\/tr>
                                                          API backlog<\/td>repo:acme-corp\/api -status:Done<\/code><\/td><\/tr>
                                                          High priority incomplete<\/td>priority:P0,P1 -status:Done<\/code><\/td><\/tr>
                                                          Upcoming week<\/td>target-date:@today..@today+7 -status:Done<\/code><\/td><\/tr>
                                                          Children of epic<\/td>parent-issue:acme-corp\/api#418<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                          A Useful Constraint<\/h3>\n\n\n\n
                                                          Projects supports OR-like matching for multiple values of the same field<\/strong>, but do not assume arbitrary cross-field Boolean expressions behave like a full query language. Design saved views around supported project filter semantics.<\/p>\n\n\n\n
                                                          \n\n\n\n
                                                          11. ESSENTIALS \u2014 Sorting, Grouping and Slicing<\/h1>\n\n\n\n
                                                          11.1 Sorting<\/h2>\n\n\n\n
                                                          Sort is about order.<\/p>\n\n\n\n
                                                          Examples:<\/p>\n\n\n\n
                                                          Priority ascending\nTarget date ascending\nEstimate descending\n<\/code><\/pre>\n\n\n\n
                                                          Use multi-field sorting when the secondary sort adds real meaning.<\/p>\n\n\n\n
                                                          Example:<\/p>\n\n\n\n
                                                          1. Priority\n2. Target date\n<\/code><\/pre>\n\n\n\n
                                                          11.2 Grouping<\/h2>\n\n\n\n
                                                          Grouping creates visual sections.<\/p>\n\n\n\n
                                                          Good grouping fields:<\/p>\n\n\n\n
                                                            \n
                                                          • Status.<\/li>\n\n\n\n
                                                          • Priority.<\/li>\n\n\n\n
                                                          • Team.<\/li>\n\n\n\n
                                                          • Repository.<\/li>\n\n\n\n
                                                          • Iteration.<\/li>\n\n\n\n
                                                          • Assignee.<\/li>\n<\/ul>\n\n\n\n
                                                            Dragging between groups can update the grouped value.<\/p>\n\n\n\n
                                                            11.3 Slicing<\/h2>\n\n\n\n
                                                            Slicing is an interactive focus mechanism. It is useful when you want a single saved view but need to switch rapidly between Team, Sprint, or Priority values.<\/p>\n\n\n\n
                                                            Think of it as:<\/p>\n\n\n\n
                                                            Filter = permanently reduce the dataset for the view\nGroup = partition visible items\nSlice = temporarily focus on one field value\n<\/code><\/pre>\n\n\n\n
                                                            11.4 Field Aggregation<\/h2>\n\n\n\n
                                                            Number fields can be summed, and views can expose item counts.<\/p>\n\n\n\n
                                                            Example capacity table:<\/p>\n\n\n\n
                                                            Team<\/th>Items<\/th>Estimate sum<\/th><\/tr><\/thead>
                                                            API<\/td>9<\/td>22<\/td><\/tr>
                                                            Web<\/td>7<\/td>18<\/td><\/tr>
                                                            Platform<\/td>5<\/td>13<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                            Treat sums as indicators, not truth, unless the team uses a consistent estimation system.<\/p>\n\n\n\n
                                                            \n\n\n\n
                                                            12. ESSENTIALS \u2014 Iteration and Sprint Management<\/h1>\n\n\n\n
                                                            12.1 Iteration Planning<\/h2>\n\n\n\n
                                                            A clean sprint model usually needs only:<\/p>\n\n\n\n
                                                            Sprint (Iteration)\nEstimate (Number)\nStatus (Single select)\nAssignee\/Team\n<\/code><\/pre>\n\n\n\n
                                                            Planning flow:<\/p>\n\n\n\n
                                                            flowchart LR\n    A[Prioritized Backlog] --> B[Select Sprint]\n    B --> C[Estimate Work]\n    C --> D[Check Capacity]\n    D --> E[Commit Sprint]\n    E --> F[Execute on Board]\n    F --> G[Review Done\/Carryover]\n<\/code><\/pre>\n\n\n\n
                                                            12.2 Iteration Configuration<\/h2>\n\n\n\n
                                                            Configure:<\/p>\n\n\n\n
                                                              \n
                                                            • Sprint duration, for example 2 weeks.<\/li>\n\n\n\n
                                                            • Start date.<\/li>\n\n\n\n
                                                            • Iteration naming.<\/li>\n\n\n\n
                                                            • Breaks such as company shutdown weeks.<\/li>\n\n\n\n
                                                            • Future iterations.<\/li>\n<\/ul>\n\n\n\n
                                                              If cadence changes, review saved views and planning conventions so teams do not silently interpret iterations differently.<\/p>\n\n\n\n
                                                              12.3 Iteration Views<\/h2>\n\n\n\n
                                                              Recommended saved views:<\/p>\n\n\n\n
                                                              Current Sprint: sprint:@current\nNext Sprint: sprint:@next\nPast Sprint: sprint:@previous\nFuture Planning: sprint:>@current\n<\/code><\/pre>\n\n\n\n
                                                              Use Board for execution and Table for planning\/review.<\/p>\n\n\n\n
                                                              12.4 Sprint Capacity<\/h2>\n\n\n\n
                                                              A simple capacity model:<\/p>\n\n\n\n
                                                              Capacity = target estimate points per team per sprint\nCommitted = sum(Estimate where Sprint=current)\nRemaining = Capacity - Committed\n<\/code><\/pre>\n\n\n\n
                                                              GitHub Projects can calculate the committed sum<\/strong> through field sums; your team provides the capacity rule.<\/p>\n\n\n\n
                                                              Do not use capacity totals to compare engineers. Story points are a planning tool, not a productivity score.<\/p>\n\n\n\n
                                                              \n\n\n\n
                                                              13. ESSENTIALS \u2014 Status and Workflow Tracking<\/h1>\n\n\n\n
                                                              13.1 Status Fields<\/h2>\n\n\n\n
                                                              Typical Status taxonomy:<\/p>\n\n\n\n
                                                              Todo\nIn Progress\nIn Review\nDone\n<\/code><\/pre>\n\n\n\n
                                                              A minimal taxonomy is usually better than 12 subtle states. Every status should answer a clear operational question.<\/p>\n\n\n\n
                                                              Example definitions:<\/p>\n\n\n\n
                                                              Status<\/th>Definition<\/th><\/tr><\/thead>
                                                              Todo<\/td>Accepted into planning but work has not started<\/td><\/tr>
                                                              In Progress<\/td>Active implementation\/investigation<\/td><\/tr>
                                                              In Review<\/td>Awaiting code\/design\/QA review<\/td><\/tr>
                                                              Done<\/td>Team’s definition of done is satisfied<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                              13.2 Workflow State<\/h2>\n\n\n\n
                                                              GitHub objects also have native states:<\/p>\n\n\n\n
                                                              Issue: open \/ closed \/ reopened\nPull request: open \/ closed \/ merged \/ reopened\n<\/code><\/pre>\n\n\n\n
                                                              These are not the same as your project Status<\/code> field.<\/p>\n\n\n\n
                                                              13.3 Project State vs Issue State<\/h2>\n\n\n\n
                                                              Example:<\/p>\n\n\n\n
                                                              Issue state: Open\nProject Status: In Review\n<\/code><\/pre>\n\n\n\n
                                                              That is perfectly valid. In Review<\/code> is a planning state; the issue remains open until completion.<\/p>\n\n\n\n
                                                              Built-in project workflows can synchronize selected transitions such as:<\/p>\n\n\n\n
                                                              Issue closed -> Status = Done\nPR merged -> Status = Done\n<\/code><\/pre>\n\n\n\n
                                                              The next chapters cover these automations.<\/p>\n\n\n\n
                                                              \n\n\n\n
                                                              Part IV \u2014 INTERMEDIATE<\/h1>\n\n\n\n
                                                              14. INTERMEDIATE \u2014 Built-In Project Workflows<\/h1>\n\n\n\n
                                                              GitHub Projects includes built-in workflows that handle common synchronization tasks without requiring GitHub Actions or API code.<\/p>\n\n\n\n
                                                              14.1 Workflow Management<\/h2>\n\n\n\n
                                                              Open a project -> project menu -> Workflows<\/strong>.<\/p>\n\n\n\n
                                                              For each built-in workflow you can typically:<\/p>\n\n\n\n
                                                                \n
                                                              • Inspect its trigger\/condition.<\/li>\n\n\n\n
                                                              • Configure the action.<\/li>\n\n\n\n
                                                              • Enable or disable it.<\/li>\n\n\n\n
                                                              • Save and turn it on.<\/li>\n<\/ul>\n\n\n\n
                                                                Two useful built-in behaviors are commonly enabled when a project is initialized:<\/p>\n\n\n\n
                                                                  \n
                                                                • Closed issues\/PRs can set project Status to\u00a0Done<\/code>.<\/li>\n\n\n\n
                                                                • Merged pull requests can set project Status to\u00a0Done<\/code>.<\/li>\n<\/ul>\n\n\n\n
                                                                  Built-In First, Custom Automation Second<\/h3>\n\n\n\n
                                                                  Use this decision rule:<\/p>\n\n\n\n
                                                                  flowchart TD\n    A[Automation requirement] --> B{Built-in workflow handles it?}\n    B -->|Yes| C[Use built-in workflow]\n    B -->|No| D{Needs repository event logic?}\n    D -->|Yes| E[GitHub Actions]\n    D -->|No| F{Needs system integration or scale?}\n    F -->|Yes| G[API \/ GitHub App]\n    F -->|No| H[CLI \/ manual operation]\n<\/code><\/pre>\n\n\n\n
                                                                  Built-in automation is easier to maintain because it does not introduce credentials, workflow files, or custom code.<\/p>\n\n\n\n
                                                                  14.2 Item Added Workflow<\/h2>\n\n\n\n
                                                                  Typical rule:<\/p>\n\n\n\n
                                                                  When: Issue or pull request is added to project\nSet: Status = Todo\n<\/code><\/pre>\n\n\n\n
                                                                  This prevents newly added items from having no status.<\/p>\n\n\n\n
                                                                  A good pattern is to reserve Todo<\/code> for accepted work. If your project also contains raw intake, consider an Inbox<\/code> or Triage<\/code> status instead.<\/p>\n\n\n\n
                                                                  14.3 Item Closed Workflow<\/h2>\n\n\n\n
                                                                  Typical synchronization:<\/p>\n\n\n\n
                                                                  Issue\/PR closed -> Status = Done\n<\/code><\/pre>\n\n\n\n
                                                                  Be careful with issues closed as not planned<\/strong>. Your reporting model may want to distinguish completed work from canceled\/rejected work instead of mapping everything to Done<\/code>.<\/p>\n\n\n\n
                                                                  14.4 Pull Request Merged Workflow<\/h2>\n\n\n\n
                                                                  Common behavior:<\/p>\n\n\n\n
                                                                  PR merged -> Status = Done\n<\/code><\/pre>\n\n\n\n
                                                                  This is useful when pull requests are direct project items. If your project primarily tracks issues and PRs are only linked metadata, the issue’s completion rule may be more important.<\/p>\n\n\n\n
                                                                  14.5 Item Reopened Workflow<\/h2>\n\n\n\n
                                                                  Reopened issues or PRs can be mapped back to an active status according to your team’s workflow.<\/p>\n\n\n\n
                                                                  Example:<\/p>\n\n\n\n
                                                                  Issue reopened -> Status = Todo\n<\/code><\/pre>\n\n\n\n
                                                                  If reopening usually means regression\/rework, you might choose a dedicated status such as Reopened<\/code> only if it provides ongoing value. Avoid adding status values for rare edge cases.<\/p>\n\n\n\n
                                                                  14.6 Status-to-Issue Automation<\/h2>\n\n\n\n
                                                                  Projects can also drive native issue state in supported workflows, for example:<\/p>\n\n\n\n
                                                                  Project Status becomes Done -> close issue\nProject Status moves out of Done -> reopen issue\n<\/code><\/pre>\n\n\n\n
                                                                  Use bidirectional synchronization carefully. Decide which system is authoritative:<\/p>\n\n\n\n
                                                                    \n
                                                                  • If engineers close issues in repository workflows, let issue state drive project status.<\/li>\n\n\n\n
                                                                  • If project operators control completion centrally, status-to-issue synchronization can fit.<\/li>\n<\/ul>\n\n\n\n
                                                                    Avoid automation loops where multiple systems repeatedly overwrite each other.<\/p>\n\n\n\n
                                                                    \n\n\n\n
                                                                    15. INTERMEDIATE \u2014 Automatic Item Addition<\/h1>\n\n\n\n
                                                                    15.1 Auto-Add Workflow<\/h2>\n\n\n\n
                                                                    The built-in Auto-add to project<\/strong> workflow adds new or updated repository items when they match configured criteria.<\/p>\n\n\n\n
                                                                    Example requirement:<\/p>\n\n\n\n
                                                                    Automatically add any open bug from acme-corp\/api.\n<\/code><\/pre>\n\n\n\n
                                                                    Example filter:<\/p>\n\n\n\n
                                                                    is:issue is:open label:bug\n<\/code><\/pre>\n\n\n\n
                                                                    Important Behavior<\/h3>\n\n\n\n
                                                                    When you enable auto-add, matching existing<\/strong> items are not necessarily backfilled merely because they already match. The workflow is designed to react as items are created or updated. Use bulk add\/import when you need an initial backfill.<\/p>\n\n\n\n
                                                                    15.2 Auto-Add Configuration<\/h2>\n\n\n\n
                                                                    Typical steps:<\/p>\n\n\n\n
                                                                      \n
                                                                    1. Open the project.<\/li>\n\n\n\n
                                                                    2. Open\u00a0Workflows<\/strong>.<\/li>\n\n\n\n
                                                                    3. Select\u00a0Auto-add to project<\/strong>.<\/li>\n\n\n\n
                                                                    4. Click\u00a0Edit<\/strong>.<\/li>\n\n\n\n
                                                                    5. Choose the repository.<\/li>\n\n\n\n
                                                                    6. Enter the filter.<\/li>\n\n\n\n
                                                                    7. Save and enable the workflow.<\/li>\n<\/ol>\n\n\n\n
                                                                      The auto-add filter supports a subset of the full project filter syntax. Common supported qualifiers include:<\/p>\n\n\n\n
                                                                      is:\nlabel:\nreason:\nassignee:\nno:\n<\/code><\/pre>\n\n\n\n
                                                                      Example recipes:<\/p>\n\n\n\n
                                                                      is:issue is:open label:roadmap\nis:pr label:needs-review\nis:issue -label:wontfix\nis:issue no:assignee\n<\/code><\/pre>\n\n\n\n
                                                                      Plan Limits<\/h3>\n\n\n\n
                                                                      The maximum number of auto-add workflows is plan-dependent. Treat this as a constrained resource. Prefer broad, understandable workflows over dozens of nearly identical rules.<\/p>\n\n\n\n
                                                                      15.3 Auto-Add Management<\/h2>\n\n\n\n
                                                                      You can duplicate an auto-add workflow and point the copy at another repository or filter.<\/p>\n\n\n\n
                                                                      Example cross-repository design:<\/p>\n\n\n\n
                                                                      Workflow 1: acme-corp\/web   -> label:delivery\nWorkflow 2: acme-corp\/api   -> label:delivery\nWorkflow 3: acme-corp\/infra -> label:delivery\n<\/code><\/pre>\n\n\n\n
                                                                      When your project spans many repositories, GitHub Actions or an App may scale better than maintaining many per-repository built-in auto-add rules.<\/p>\n\n\n\n
                                                                      \n\n\n\n
                                                                      16. INTERMEDIATE \u2014 Automatic Archiving<\/h1>\n\n\n\n
                                                                      16.1 Auto-Archive Workflow<\/h2>\n\n\n\n
                                                                      Auto-archive keeps active views focused by archiving items that meet selected criteria.<\/p>\n\n\n\n
                                                                      A practical retention rule might be:<\/p>\n\n\n\n
                                                                      is:closed updated:<@today-30d\n<\/code><\/pre>\n\n\n\n
                                                                      or a policy based on merged\/closed items and age.<\/p>\n\n\n\n
                                                                      The auto-archive workflow supports a restricted filter set, including item state\/close reason and updated-time criteria.<\/p>\n\n\n\n
                                                                      Why Archive Instead of Delete?<\/h3>\n\n\n\n
                                                                      Archive preserves project field context and allows restoration. This is ideal for normal completion cleanup.<\/p>\n\n\n\n
                                                                      16.2 Archive Management<\/h2>\n\n\n\n
                                                                      A healthy project lifecycle is:<\/p>\n\n\n\n
                                                                      flowchart LR\n    A[Active] --> B[Done]\n    B --> C[Retention Window]\n    C --> D[Archived]\n    D --> E{Needed again?}\n    E -->|Yes| F[Restore]\n    E -->|No| G[Remain archived]\n<\/code><\/pre>\n\n\n\n
                                                                      Use manual\/bulk archive for one-time cleanup and automatic archiving for steady-state hygiene.<\/p>\n\n\n\n
                                                                      \n\n\n\n
                                                                      17. INTERMEDIATE \u2014 Project Insights<\/h1>\n\n\n\n
                                                                      17.1 Insights Fundamentals<\/h2>\n\n\n\n
                                                                      Insights turns project data into charts. It is useful for operational visibility, workload distribution, status composition, and progress communication.<\/p>\n\n\n\n
                                                                      A chart is only as reliable as the fields behind it. If half your issues have no Priority, a Priority chart is incomplete by design.<\/p>\n\n\n\n
                                                                      17.2 Creating Charts<\/h2>\n\n\n\n
                                                                      Typical flow:<\/p>\n\n\n\n
                                                                        \n
                                                                      1. Open project\u00a0Insights<\/strong>.<\/li>\n\n\n\n
                                                                      2. Create a new chart.<\/li>\n\n\n\n
                                                                      3. Name it clearly.<\/li>\n\n\n\n
                                                                      4. Apply a chart filter if needed.<\/li>\n\n\n\n
                                                                      5. Configure layout\/axes\/grouping.<\/li>\n\n\n\n
                                                                      6. Save changes.<\/li>\n<\/ol>\n\n\n\n
                                                                        Example chart names:<\/p>\n\n\n\n
                                                                        Current Sprint by Status\nOpen P0\/P1 by Team\nEstimate by Team\nWork by Repository\n<\/code><\/pre>\n\n\n\n
                                                                        17.3 Chart Configuration<\/h2>\n\n\n\n
                                                                        Common controls include:<\/p>\n\n\n\n
                                                                          \n
                                                                        • Layout\/chart type.<\/li>\n\n\n\n
                                                                        • X-axis field.<\/li>\n\n\n\n
                                                                        • Optional Group by field.<\/li>\n\n\n\n
                                                                        • Y-axis aggregation when number fields are used.<\/li>\n\n\n\n
                                                                        • Filter.<\/li>\n<\/ul>\n\n\n\n
                                                                          Example:<\/p>\n\n\n\n
                                                                          Filter: sprint:@current\nX-axis: Status\nGroup by: Team\nY-axis: Sum of Estimate\n<\/code><\/pre>\n\n\n\n
                                                                          17.4 Numeric Aggregations<\/h2>\n\n\n\n
                                                                          For number fields, supported chart calculations can include:<\/p>\n\n\n\n
                                                                            \n
                                                                          • Count.<\/li>\n\n\n\n
                                                                          • Sum.<\/li>\n\n\n\n
                                                                          • Average.<\/li>\n\n\n\n
                                                                          • Minimum.<\/li>\n\n\n\n
                                                                          • Maximum.<\/li>\n<\/ul>\n\n\n\n
                                                                            Use Count<\/strong> for item volume and Sum<\/strong> for additive metrics such as estimates. Be cautious with averages of story points; they often say little about delivery health.<\/p>\n\n\n\n
                                                                            17.5 Insight Use Cases<\/h2>\n\n\n\n
                                                                            Question<\/th>Example chart<\/th><\/tr><\/thead>
                                                                            Where is work stuck?<\/td>Count by Status<\/td><\/tr>
                                                                            Which priorities dominate?<\/td>Count by Priority<\/td><\/tr>
                                                                            Is sprint load balanced?<\/td>Sum Estimate grouped by Team<\/td><\/tr>
                                                                            Which repo carries most work?<\/td>Count by Repository<\/td><\/tr>
                                                                            Who is overloaded?<\/td>Count\/Sum by Assignee, interpreted carefully<\/td><\/tr>
                                                                            Is the roadmap risk-heavy?<\/td>P0\/P1 incomplete by Target date<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                            Insights is a lightweight project reporting layer, not a replacement for a full analytics warehouse when you need historical cycle-time, lead-time, or complex cross-project BI.<\/p>\n\n\n\n
                                                                            \n\n\n\n
                                                                            18. INTERMEDIATE \u2014 Project Templates<\/h1>\n\n\n\n
                                                                            18.1 Built-In Templates<\/h2>\n\n\n\n
                                                                            GitHub provides templates for common project patterns. Use them when they are close to your desired operating model and then simplify them if needed.<\/p>\n\n\n\n
                                                                            A template should reduce setup cost, not force a team into fields it does not understand.<\/p>\n\n\n\n
                                                                            18.2 Organization Templates<\/h2>\n\n\n\n
                                                                            Organization templates let you standardize:<\/p>\n\n\n\n
                                                                              \n
                                                                            • Fields.<\/li>\n\n\n\n
                                                                            • Views.<\/li>\n\n\n\n
                                                                            • Draft issues.<\/li>\n\n\n\n
                                                                            • Configured workflows, with auto-add exceptions.<\/li>\n\n\n\n
                                                                            • Insights.<\/li>\n<\/ul>\n\n\n\n
                                                                              A project admin can mark an organization-owned project as a template, subject to organization permissions.<\/p>\n\n\n\n
                                                                              Template Example<\/h3>\n\n\n\n
                                                                              Engineering Delivery Template\n  Views:\n    - Triage\n    - Backlog\n    - Current Sprint\n    - Roadmap\n  Fields:\n    - Status\n    - Priority\n    - Sprint\n    - Estimate\n    - Team\n  Workflows:\n    - Set Todo when added\n    - Set Done when closed\n    - Set Done when PR merged\n  Insights:\n    - Sprint by Status\n    - Estimate by Team\n<\/code><\/pre>\n\n\n\n
                                                                              18.3 Recommended Templates<\/h2>\n\n\n\n
                                                                              Organization owners can curate a limited set of recommended templates so users see preferred standards first during project creation.<\/p>\n\n\n\n
                                                                              Use recommendations for officially supported operating models, not every experimental template.<\/p>\n\n\n\n
                                                                              18.4 Template Lifecycle<\/h2>\n\n\n\n
                                                                              Treat a template like a product:<\/p>\n\n\n\n
                                                                              flowchart LR\n    A[Design] --> B[Pilot]\n    B --> C[Publish template]\n    C --> D[Teams adopt]\n    D --> E[Collect feedback]\n    E --> F[Revise standard]\n    F --> C\n<\/code><\/pre>\n\n\n\n
                                                                              Because existing projects do not magically inherit every later template change, document version changes and provide a migration path for material field\/status changes.<\/p>\n\n\n\n
                                                                              \n\n\n\n
                                                                              19. INTERMEDIATE \u2014 Project Updates<\/h1>\n\n\n\n
                                                                              19.1 Status Updates<\/h2>\n\n\n\n
                                                                              Project updates communicate high-level state separately from individual item status.<\/p>\n\n\n\n
                                                                              A project update can include:<\/p>\n\n\n\n
                                                                                \n
                                                                              • Project health\/status.<\/li>\n\n\n\n
                                                                              • Start date.<\/li>\n\n\n\n
                                                                              • Target date.<\/li>\n\n\n\n
                                                                              • Markdown message.<\/li>\n<\/ul>\n\n\n\n
                                                                                Example update:<\/p>\n\n\n\n
                                                                                ### Weekly update\nAPI migration is on track. Web rollout moved by three days because browser regression testing found two P1 issues.\n\n- API: complete\n- Web: 80%\n- Infra: complete\n- Decision needed: approve phased rollout by Friday\n<\/code><\/pre>\n\n\n\n
                                                                                19.2 Project Health<\/h2>\n\n\n\n
                                                                                Typical health statuses include concepts such as:<\/p>\n\n\n\n
                                                                                On track\nAt risk\nOff track\nComplete\nInactive\n<\/code><\/pre>\n\n\n\n
                                                                                Define the criteria in your project README. For example:<\/p>\n\n\n\n
                                                                                Health<\/th>Internal definition example<\/th><\/tr><\/thead>
                                                                                On track<\/td>Current plan remains achievable<\/td><\/tr>
                                                                                At risk<\/td>Material risk exists but recovery plan is plausible<\/td><\/tr>
                                                                                Off track<\/td>Target cannot be met without replan\/scope\/date change<\/td><\/tr>
                                                                                Complete<\/td>Project objective is completed<\/td><\/tr>
                                                                                Inactive<\/td>Work intentionally paused\/not currently active<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                19.3 Update History<\/h2>\n\n\n\n
                                                                                Project updates form a history of project-level communication. Stakeholders with appropriate access can review the latest update and prior updates, and can subscribe to updates.<\/p>\n\n\n\n
                                                                                Use updates for decision-quality summaries, not as a duplicate of the board.<\/p>\n\n\n\n
                                                                                19.4 Project-Level Planning Dates<\/h2>\n\n\n\n
                                                                                Project start\/target dates describe the overall project<\/strong>. Item-level date fields describe individual work items. Keep these concepts separate.<\/p>\n\n\n\n
                                                                                \n\n\n\n
                                                                                20. INTERMEDIATE \u2014 Project README and Documentation<\/h1>\n\n\n\n
                                                                                Every serious shared project should explain how to use it.<\/p>\n\n\n\n
                                                                                Recommended README structure:<\/p>\n\n\n\n
                                                                                # Acme Platform Delivery\n\n## Purpose\nTrack committed and candidate delivery work across web, API, and infrastructure.\n\n## Scope\nIncluded: customer-facing platform delivery.\nExcluded: internal support requests and ad-hoc incidents.\n\n## Field definitions\n- Status: execution state.\n- Priority: P0-P3 according to impact\/urgency policy.\n- Sprint: committed delivery iteration.\n- Estimate: team-relative planning points.\n\n## Definition of Done\n1. Implementation merged.\n2. Required tests pass.\n3. Documentation updated when applicable.\n4. Rollout\/verification complete.\n\n## View definitions\n- Triage: missing owner or priority.\n- Backlog: prioritized uncommitted work.\n- Current Sprint: sprint execution board.\n- Roadmap: incomplete work with planning dates.\n\n## Automation\n- Added items -> Todo.\n- Closed items -> Done.\n- Done older than retention period -> archived.\n\n## Ownership\nProject admins: Platform PM + Engineering Manager.\n<\/code><\/pre>\n\n\n\n
                                                                                Documentation Rule<\/h3>\n\n\n\n
                                                                                If a new team member cannot explain the difference between Priority<\/code>, Severity<\/code>, Status<\/code>, and Type<\/code> after reading the README, the metadata model is under-documented.<\/p>\n\n\n\n
                                                                                \n\n\n\n
                                                                                21. INTERMEDIATE \u2014 Project Visibility<\/h1>\n\n\n\n
                                                                                21.1 Visibility Types<\/h2>\n\n\n\n
                                                                                Projects can be:<\/p>\n\n\n\n
                                                                                  \n
                                                                                • Private<\/strong>\u00a0\u2014 visible only to people with sufficient project access.<\/li>\n\n\n\n
                                                                                • Public<\/strong>\u00a0\u2014 visible on the internet.<\/li>\n<\/ul>\n\n\n\n
                                                                                  Critical Security Detail<\/h3>\n\n\n\n
                                                                                  Public project visibility does not<\/strong> grant repository access. If a project references items from a private repository, viewers who lack repository permission cannot see the private content simply because the project itself is public.<\/p>\n\n\n\n
                                                                                  However, project-level metadata and structure can still reveal planning information. Treat public visibility as a deliberate publishing decision.<\/p>\n\n\n\n
                                                                                  21.2 Visibility Management<\/h2>\n\n\n\n
                                                                                  Project admins\/organization owners can control visibility according to organization policy.<\/p>\n\n\n\n
                                                                                  Before changing a project to public, review:<\/p>\n\n\n\n
                                                                                    \n
                                                                                  • Project title\/README.<\/li>\n\n\n\n
                                                                                  • Custom field names and values.<\/li>\n\n\n\n
                                                                                  • Status updates.<\/li>\n\n\n\n
                                                                                  • Linked repository information.<\/li>\n\n\n\n
                                                                                  • Draft issues.<\/li>\n\n\n\n
                                                                                  • Strategic dates.<\/li>\n\n\n\n
                                                                                  • Customer\/product codenames.<\/li>\n<\/ul>\n\n\n\n
                                                                                    \n\n\n\n
                                                                                    22. INTERMEDIATE \u2014 Project Access and Permissions<\/h1>\n\n\n\n
                                                                                    22.1 Permission Levels<\/h2>\n\n\n\n
                                                                                    Organization projects commonly work with these roles:<\/p>\n\n\n\n
                                                                                    Role<\/th>Capability summary<\/th><\/tr><\/thead>
                                                                                    No access<\/td>No direct project access through base role<\/td><\/tr>
                                                                                    Read<\/td>View the project<\/td><\/tr>
                                                                                    Write<\/td>View and edit project content<\/td><\/tr>
                                                                                    Admin<\/td>Edit and manage project settings\/access<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                    Repository permissions still matter. Project access does not automatically grant access to private repository items.<\/p>\n\n\n\n
                                                                                    22.2 Organization Access<\/h2>\n\n\n\n
                                                                                    An organization project can use a base role<\/strong> for organization members and then add team or individual access.<\/p>\n\n\n\n
                                                                                    Example model:<\/p>\n\n\n\n
                                                                                    Base role: Read\nengineering-team: Write\nproduct-team: Write\nproject-admins: Admin\noutside collaborators: Explicit only\n<\/code><\/pre>\n\n\n\n
                                                                                    This is usually safer and easier to maintain than granting individuals ad hoc write access one by one.<\/p>\n\n\n\n
                                                                                    22.3 User Project Access<\/h2>\n\n\n\n
                                                                                    User-owned projects can invite collaborators and grant project roles, but do not provide the same organization governance model as organization-owned projects.<\/p>\n\n\n\n
                                                                                    22.4 Permission Administration<\/h2>\n\n\n\n
                                                                                    Use least privilege:<\/p>\n\n\n\n
                                                                                      \n
                                                                                    • Stakeholder who only needs visibility -> Read.<\/li>\n\n\n\n
                                                                                    • Contributor who manages items\/fields -> Write.<\/li>\n\n\n\n
                                                                                    • Small set of project maintainers -> Admin.<\/li>\n<\/ul>\n\n\n\n
                                                                                      Do not grant Admin merely because someone needs to move cards.<\/p>\n\n\n\n
                                                                                      \n\n\n\n
                                                                                      23. INTERMEDIATE \u2014 Linking Projects<\/h1>\n\n\n\n
                                                                                      23.1 Repository Linking<\/h2>\n\n\n\n
                                                                                      Linking a project to a repository makes it discoverable from that repository’s Projects<\/strong> tab.<\/p>\n\n\n\n
                                                                                      Only relevant projects owned by the same user\/organization can be linked in this way.<\/p>\n\n\n\n
                                                                                      Default Repository<\/h3>\n\n\n\n
                                                                                      A project can have a default repository. New issues created from the project can then default to that repository.<\/p>\n\n\n\n
                                                                                      Use this when one repository owns most work. For a truly balanced multi-repository project, be careful that the default does not cause accidental issue creation in the wrong repo.<\/p>\n\n\n\n
                                                                                      23.2 Team Linking<\/h2>\n\n\n\n
                                                                                      Linking a project to a team improves discoverability and can grant team project access according to GitHub’s team-link behavior.<\/p>\n\n\n\n
                                                                                      A team page then becomes a useful entry point for:<\/p>\n\n\n\n
                                                                                      Team -> Projects -> Delivery project -> Saved views\n<\/code><\/pre>\n\n\n\n
                                                                                      23.3 Cross-Repository Planning<\/h2>\n\n\n\n
                                                                                      An organization project can combine work from many repositories.<\/p>\n\n\n\n
                                                                                      Example:<\/p>\n\n\n\n
                                                                                      flowchart TD\n    A[Acme Platform Delivery] --> B[web issues\/PRs]\n    A --> C[api issues\/PRs]\n    A --> D[infra issues\/PRs]\n    A --> E[shared roadmap]\n    A --> F[shared sprint view]\n<\/code><\/pre>\n\n\n\n
                                                                                      Use the Repository field as a natural dimension for filtering\/grouping and reporting.<\/p>\n\n\n\n
                                                                                      \n\n\n\n
                                                                                      24. INTERMEDIATE \u2014 Project Lifecycle Management<\/h1>\n\n\n\n
                                                                                      A project itself has a lifecycle.<\/p>\n\n\n\n
                                                                                      Typical states\/actions:<\/p>\n\n\n\n
                                                                                      Create -> Active -> Close -> Reopen (if needed) -> Delete (rare)\n<\/code><\/pre>\n\n\n\n
                                                                                      Close vs Delete<\/h3>\n\n\n\n
                                                                                        \n
                                                                                      • Close<\/strong>\u00a0when the project is no longer active but should remain available as historical context.<\/li>\n\n\n\n
                                                                                      • Delete<\/strong>\u00a0only when the project is disposable, erroneous, or deliberately being permanently removed.<\/li>\n<\/ul>\n\n\n\n
                                                                                        End-of-Project Checklist<\/h3>\n\n\n\n
                                                                                          \n
                                                                                        • Post final project update.<\/li>\n\n\n\n
                                                                                        • Mark overall health\/status complete as appropriate.<\/li>\n\n\n\n
                                                                                        • Archive or retain finished items according to policy.<\/li>\n\n\n\n
                                                                                        • Export data if required for records.<\/li>\n\n\n\n
                                                                                        • Remove unnecessary automation credentials\/workflows.<\/li>\n\n\n\n
                                                                                        • Close the project.<\/li>\n\n\n\n
                                                                                        • Keep documentation readable for future audit\/reference.<\/li>\n<\/ul>\n\n\n\n
                                                                                          \n\n\n\n
                                                                                          25. INTERMEDIATE \u2014 Exporting Project Data<\/h1>\n\n\n\n
                                                                                          Current GitHub Projects view export downloads TSV (tab-separated values)<\/strong> data.<\/p>\n\n\n\n
                                                                                          Typical flow:<\/p>\n\n\n\n
                                                                                          Project view -> View menu -> Export view data\n<\/code><\/pre>\n\n\n\n
                                                                                          Why the Distinction Matters<\/h3>\n\n\n\n
                                                                                          Many tutorials casually say “CSV export,” but the current GitHub UI exports a .tsv<\/code> view. Most spreadsheet\/data tools can open TSV directly or convert it to CSV.<\/p>\n\n\n\n
                                                                                          Example shell conversion:<\/p>\n\n\n\n
                                                                                          python - <<'PY'\nimport csv\n\nwith open('project.tsv', newline='', encoding='utf-8') as src, \\\n     open('project.csv', 'w', newline='', encoding='utf-8') as dst:\n    reader = csv.reader(src, delimiter='\\t')\n    writer = csv.writer(dst)\n    writer.writerows(reader)\nPY\n<\/code><\/pre>\n\n\n\n
                                                                                          Export Use Cases<\/h3>\n\n\n\n
                                                                                            \n
                                                                                          • Offline analysis.<\/li>\n\n\n\n
                                                                                          • Audit snapshots.<\/li>\n\n\n\n
                                                                                          • Ad-hoc reporting.<\/li>\n\n\n\n
                                                                                          • Spreadsheet sharing.<\/li>\n\n\n\n
                                                                                          • Loading project data into a BI\/data pipeline.<\/li>\n<\/ul>\n\n\n\n
                                                                                            Remember that exported data is a snapshot, not a live integration.<\/p>\n\n\n\n
                                                                                            \n\n\n\n
                                                                                            26. INTERMEDIATE \u2014 Project Command Palette<\/h1>\n\n\n\n
                                                                                            The project command palette speeds up keyboard-driven operations.<\/p>\n\n\n\n
                                                                                            Open it with:<\/p>\n\n\n\n
                                                                                            macOS: Command + K\nWindows\/Linux: Ctrl + K\n<\/code><\/pre>\n\n\n\n
                                                                                            Examples of tasks you can discover\/launch from the palette include:<\/p>\n\n\n\n
                                                                                              \n
                                                                                            • Add items.<\/li>\n\n\n\n
                                                                                            • Filter-related actions.<\/li>\n\n\n\n
                                                                                            • View operations.<\/li>\n\n\n\n
                                                                                            • Field\/item operations exposed by the current UI.<\/li>\n<\/ul>\n\n\n\n
                                                                                              Do not memorize every command. Memorize the launcher and search by intent.<\/p>\n\n\n\n
                                                                                              \n\n\n\n
                                                                                              27. INTERMEDIATE \u2014 Keyboard and Productivity Features<\/h1>\n\n\n\n
                                                                                              High-throughput project management depends on reducing repetitive clicks.<\/p>\n\n\n\n
                                                                                              Useful patterns include:<\/p>\n\n\n\n
                                                                                                \n
                                                                                              • Inline editing.<\/li>\n\n\n\n
                                                                                              • Multi-select.<\/li>\n\n\n\n
                                                                                              • Bulk edits.<\/li>\n\n\n\n
                                                                                              • Drag-and-drop.<\/li>\n\n\n\n
                                                                                              • Command palette.<\/li>\n\n\n\n
                                                                                              • Quick item creation.<\/li>\n\n\n\n
                                                                                              • Saved views.<\/li>\n\n\n\n
                                                                                              • Direct view URLs.<\/li>\n<\/ul>\n\n\n\n
                                                                                                Multi-Select Mindset<\/h3>\n\n\n\n
                                                                                                Instead of editing 30 items individually:<\/p>\n\n\n\n
                                                                                                Filter -> Select matching rows -> Bulk update -> Verify\n<\/code><\/pre>\n\n\n\n
                                                                                                For example:<\/p>\n\n\n\n
                                                                                                Filter: sprint:@next no:priority\nSelect all relevant items\nSet Priority = P2\n<\/code><\/pre>\n\n\n\n
                                                                                                Use bulk operations deliberately; a fast mistake is still a mistake.<\/p>\n\n\n\n
                                                                                                \n\n\n\n
                                                                                                28. INTERMEDIATE \u2014 Project Planning Patterns<\/h1>\n\n\n\n
                                                                                                This chapter combines the primitives into practical operating models.<\/p>\n\n\n\n
                                                                                                28.1 Backlog Management<\/h2>\n\n\n\n
                                                                                                Recommended configuration:<\/p>\n\n\n\n
                                                                                                Layout: Table\nFilter: -status:Done no:sprint\nGroup by: Priority\nSort: Priority, then Target date\nFields: Type, Priority, Estimate, Team, Assignee\n<\/code><\/pre>\n\n\n\n
                                                                                                Backlog workflow:<\/p>\n\n\n\n
                                                                                                flowchart LR\n    A[Intake] --> B[Triage]\n    B --> C[Prioritized Backlog]\n    C --> D[Sprint \/ Release Commitment]\n    D --> E[Execution]\n    E --> F[Done]\n<\/code><\/pre>\n\n\n\n
                                                                                                28.2 Sprint Planning<\/h2>\n\n\n\n
                                                                                                Recommended configuration:<\/p>\n\n\n\n
                                                                                                Sprint field: Iteration\nExecution view: Board\nFilter: sprint:@current\nColumns: Status\nGroup by: Team\nField sum: Estimate\n<\/code><\/pre>\n\n\n\n
                                                                                                Planning steps:<\/p>\n\n\n\n
                                                                                                  \n
                                                                                                1. Start from prioritized backlog.<\/li>\n\n\n\n
                                                                                                2. Assign Sprint to candidate work.<\/li>\n\n\n\n
                                                                                                3. Confirm estimates and owners.<\/li>\n\n\n\n
                                                                                                4. Check field sums\/capacity.<\/li>\n\n\n\n
                                                                                                5. Resolve over-commitment.<\/li>\n\n\n\n
                                                                                                6. Save the sprint view.<\/li>\n<\/ol>\n\n\n\n
                                                                                                  28.3 Kanban<\/h2>\n\n\n\n
                                                                                                  Recommended configuration:<\/p>\n\n\n\n
                                                                                                  Layout: Board\nColumns: Status\nWIP limits: Selected active columns\nNo required iteration\n<\/code><\/pre>\n\n\n\n
                                                                                                  Kanban is continuous flow. Avoid forcing sprint concepts into the model if the team does not use time boxes.<\/p>\n\n\n\n
                                                                                                  28.4 Roadmap<\/h2>\n\n\n\n
                                                                                                  Recommended configuration:<\/p>\n\n\n\n
                                                                                                  Layout: Roadmap\nStart: Start date\nTarget: Target date\nGroup by: Team or Workstream\nMarkers: Milestones\nZoom: Quarter\n<\/code><\/pre>\n\n\n\n
                                                                                                  Roadmap items should represent decision-relevant work. A roadmap with hundreds of tiny tasks becomes a Gantt-shaped backlog rather than a strategy view.<\/p>\n\n\n\n
                                                                                                  28.5 Portfolio Tracking<\/h2>\n\n\n\n
                                                                                                  A portfolio project can combine multiple repositories\/teams with fields such as:<\/p>\n\n\n\n
                                                                                                  Strategic initiative\nTeam\nWorkstream\nPriority\nTarget quarter\nHealth\n<\/code><\/pre>\n\n\n\n
                                                                                                  Prefer a separate portfolio project only when portfolio metadata or access differs materially from team delivery projects. Do not duplicate all fields and manually synchronize them without a clear need.<\/p>\n\n\n\n
                                                                                                  \n\n\n\n
                                                                                                  Part V \u2014 ADVANCED AUTOMATION, APIs, SECURITY & GOVERNANCE<\/h1>\n\n\n\n
                                                                                                  29. ADVANCED \u2014 GitHub Actions + Projects<\/h1>\n\n\n\n
                                                                                                  GitHub Actions is useful when a project update must react to repository events or when the built-in project workflows are not expressive enough.<\/p>\n\n\n\n
                                                                                                  A good rule is:<\/p>\n\n\n\n
                                                                                                  Built-in workflow can do it?  -> Use the built-in workflow.\nRepository event + custom rule? -> Consider GitHub Actions.\nCross-system\/business logic?     -> Consider an App or external automation.\n<\/code><\/pre>\n\n\n\n
                                                                                                  29.1 Projects Automation with Actions<\/h2>\n\n\n\n
                                                                                                  Typical triggers include:<\/p>\n\n\n\n
                                                                                                    \n
                                                                                                  • issues<\/code>\u00a0\u2014 issue opened, labeled, closed, reopened, assigned.<\/li>\n\n\n\n
                                                                                                  • pull_request<\/code>\u00a0\u2014 PR opened, converted to ready-for-review, closed, merged.<\/li>\n\n\n\n
                                                                                                  • workflow_dispatch<\/code>\u00a0\u2014 manual automation.<\/li>\n\n\n\n
                                                                                                  • schedule<\/code>\u00a0\u2014 periodic cleanup or governance checks.<\/li>\n\n\n\n
                                                                                                  • release\/deployment events \u2014 update release-oriented metadata.<\/li>\n<\/ul>\n\n\n\n
                                                                                                    Automation Architecture<\/h3>\n\n\n\n
                                                                                                    flowchart LR\n    A[GitHub Event] --> B[GitHub Actions Workflow]\n    B --> C{What is needed?}\n    C -->|Add item| D[actions\/add-to-project]\n    C -->|Update fields| E[gh project or GraphQL API]\n    C -->|Complex integration| F[GitHub App \/ External Service]\n    D --> G[GitHub Project]\n    E --> G\n    F --> G\n<\/code><\/pre>\n\n\n\n
                                                                                                    Example: Automatically Add Labeled Issues to a Project<\/h3>\n\n\n\n
                                                                                                    \n
                                                                                                    Authentication matters. The repository-scoped GITHUB_TOKEN<\/code> is not sufficient for accessing organization\/user Projects. Use a token with appropriate Projects access, preferably a GitHub App installation token for organization automation or an appropriately scoped PAT where suitable.<\/p>\n<\/blockquote>\n\n\n\n
                                                                                                    name: Add roadmap issues to project\n\non:\n  issues:\n    types: [opened, labeled]\n\njobs:\n  add-to-project:\n    if: contains(github.event.issue.labels.*.name, 'roadmap')\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Add issue to GitHub Project\n        uses: actions\/add-to-project@v2\n        with:\n          project-url: https:\/\/github.com\/orgs\/acme-corp\/projects\/7\n          github-token: ${{ secrets.PROJECT_TOKEN }}\n<\/code><\/pre>\n\n\n\n
                                                                                                    Use the built-in Auto-add to project<\/strong> workflow instead when a filter such as label:roadmap<\/code> already expresses the requirement. The Action is more useful when additional repository logic is required.<\/p>\n\n\n\n
                                                                                                    29.2 Common Automation Patterns<\/h2>\n\n\n\n
                                                                                                    Pattern<\/th>Example trigger<\/th>Action<\/th><\/tr><\/thead>
                                                                                                    Add project item<\/td>Issue gets roadmap<\/code> label<\/td>Add issue to project<\/td><\/tr>
                                                                                                    Set priority<\/td>Issue gets severity:critical<\/code><\/td>Set Priority = P0<\/code><\/td><\/tr>
                                                                                                    Set Status<\/td>Deployment succeeds<\/td>Set Status = Released<\/code><\/td><\/tr>
                                                                                                    Set date<\/td>Release created<\/td>Set target\/release date<\/td><\/tr>
                                                                                                    Assign iteration<\/td>Issue receives sprint label<\/td>Set Iteration field<\/td><\/tr>
                                                                                                    Archive old work<\/td>Scheduled job<\/td>Archive matching completed items<\/td><\/tr>
                                                                                                    Cross-repository intake<\/td>Events in many repositories<\/td>Add to shared organization project<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                    Example: Event \u2192 Rule \u2192 Project Field<\/h3>\n\n\n\n
                                                                                                    sequenceDiagram\n    participant Dev as Developer\n    participant GH as GitHub Issue\n    participant GA as GitHub Actions\n    participant API as Projects API\n    participant P as Project\n\n    Dev->>GH: Add severity:critical label\n    GH->>GA: issues.labeled event\n    GA->>API: Resolve project\/item\/field IDs\n    GA->>API: Set Priority = P0\n    API->>P: Persist field value\n<\/code><\/pre>\n\n\n\n
                                                                                                    29.3 Authentication<\/h2>\n\n\n\n
                                                                                                    The four terms below are easy to confuse:<\/p>\n\n\n\n
                                                                                                    Credential<\/th>Good fit<\/th>Important note<\/th><\/tr><\/thead>
                                                                                                    GITHUB_TOKEN<\/code><\/td>Repository-scoped Actions work<\/td>Do not assume it can access organization\/user Projects<\/td><\/tr>
                                                                                                    Classic PAT<\/td>Scripts\/CLI where policy permits<\/td>GraphQL Projects commonly needs read:project<\/code> for read and project<\/code> for write<\/td><\/tr>
                                                                                                    Fine-grained PAT<\/td>Endpoint-specific REST automation<\/td>Check the exact endpoint’s Projects permission requirements<\/td><\/tr>
                                                                                                    GitHub App installation token<\/td>Organization-scale automation<\/td>Preferred for controlled, revocable, least-privilege integrations<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                    Secure Token Pattern<\/h3>\n\n\n\n
                                                                                                    Secret store\n   |\n   v\nGitHub Actions secret \/ App token\n   |\n   v\nShort-lived workflow execution\n   |\n   +--> Project API\n   |\n   +--> No token printed in logs\n<\/code><\/pre>\n\n\n\n
                                                                                                    Do not:<\/p>\n\n\n\n
                                                                                                      \n
                                                                                                    • hard-code PATs in workflow YAML;<\/li>\n\n\n\n
                                                                                                    • echo access tokens;<\/li>\n\n\n\n
                                                                                                    • give automation organization-wide permissions when one project is enough;<\/li>\n\n\n\n
                                                                                                    • use a personal long-lived token for a business-critical integration without a lifecycle plan.<\/li>\n<\/ul>\n\n\n\n
                                                                                                      \n\n\n\n
                                                                                                      30. ADVANCED \u2014 GraphQL API for Projects<\/h1>\n\n\n\n
                                                                                                      GitHub’s GraphQL API exposes the current Projects model as ProjectV2<\/code><\/strong>. GraphQL is still the most expressive API surface when you need rich discovery of Projects objects, node IDs, field configurations, and mutations.<\/p>\n\n\n\n
                                                                                                      30.1 ProjectV2<\/code> API<\/h2>\n\n\n\n
                                                                                                      The API frequently works with two identifiers:<\/p>\n\n\n\n
                                                                                                        \n
                                                                                                      • Project number<\/strong>\u00a0\u2014 the human-facing number in URLs, such as\u00a07<\/code>.<\/li>\n\n\n\n
                                                                                                      • Node ID<\/strong>\u00a0\u2014 the opaque GraphQL ID used by most mutations.<\/li>\n<\/ul>\n\n\n\n
                                                                                                        https://github.com\/orgs\/acme-corp\/projects\/7\n                                      ^\n                                project number\n<\/code><\/pre>\n\n\n\n
                                                                                                        The normal automation flow is:<\/p>\n\n\n\n
                                                                                                        flowchart LR\n    A[Know owner + project number] --> B[Query ProjectV2]\n    B --> C[Get project node ID]\n    C --> D[Query fields\/items]\n    D --> E[Get item\/field\/option IDs]\n    E --> F[Run mutation]\n<\/code><\/pre>\n\n\n\n
                                                                                                        30.2 Project Queries<\/h2>\n\n\n\n
                                                                                                        Fetch an Organization Project and Its Fields<\/h3>\n\n\n\n
                                                                                                        query($login: String!, $number: Int!) {\n  organization(login: $login) {\n    projectV2(number: $number) {\n      id\n      number\n      title\n      url\n      fields(first: 50) {\n        nodes {\n          ... on ProjectV2Field {\n            id\n            name\n            dataType\n          }\n          ... on ProjectV2SingleSelectField {\n            id\n            name\n            options {\n              id\n              name\n            }\n          }\n          ... on ProjectV2IterationField {\n            id\n            name\n            configuration {\n              iterations {\n                id\n                title\n                startDate\n                duration\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}\n<\/code><\/pre>\n\n\n\n
                                                                                                        Run it with GitHub CLI:<\/p>\n\n\n\n
                                                                                                        gh api graphql \\\n  -f query='query($login:String!,$number:Int!){\n    organization(login:$login){\n      projectV2(number:$number){id number title url}\n    }\n  }' \\\n  -F login='acme-corp' \\\n  -F number=7\n<\/code><\/pre>\n\n\n\n
                                                                                                        Read Project Items<\/h3>\n\n\n\n
                                                                                                        query($login: String!, $number: Int!) {\n  organization(login: $login) {\n    projectV2(number: $number) {\n      items(first: 100) {\n        nodes {\n          id\n          type\n          content {\n            ... on Issue {\n              number\n              title\n              url\n            }\n            ... on PullRequest {\n              number\n              title\n              url\n            }\n            ... on DraftIssue {\n              title\n            }\n          }\n        }\n      }\n    }\n  }\n}\n<\/code><\/pre>\n\n\n\n
                                                                                                        For larger projects, implement GraphQL pagination rather than assuming first: 100<\/code> is the whole project.<\/p>\n\n\n\n
                                                                                                        30.3 Project Mutations<\/h2>\n\n\n\n
                                                                                                        Common current mutations include operations to:<\/p>\n\n\n\n
                                                                                                          \n
                                                                                                        • create, update, close\/reopen, and delete a project;<\/li>\n\n\n\n
                                                                                                        • manage project collaborators;<\/li>\n\n\n\n
                                                                                                        • add issues\/PRs or draft issues;<\/li>\n\n\n\n
                                                                                                        • update or clear item field values;<\/li>\n\n\n\n
                                                                                                        • move\/reorder, archive, or delete items;<\/li>\n\n\n\n
                                                                                                        • create\/update\/delete fields;<\/li>\n\n\n\n
                                                                                                        • create\/update views;<\/li>\n\n\n\n
                                                                                                        • link\/unlink repositories and teams;<\/li>\n\n\n\n
                                                                                                        • manage project templates and status updates.<\/li>\n<\/ul>\n\n\n\n
                                                                                                          Update Project Metadata<\/h3>\n\n\n\n
                                                                                                          mutation {\n  updateProjectV2(\n    input: {\n      projectId: \"PROJECT_ID\"\n      title: \"Acme Platform Delivery\"\n      public: false\n      shortDescription: \"Cross-repository platform delivery\"\n      readme: \"# Delivery Project\\n\\nTeam operating guide.\"\n    }\n  ) {\n    projectV2 {\n      id\n      title\n      public\n    }\n  }\n}\n<\/code><\/pre>\n\n\n\n
                                                                                                          30.4 Project Item Mutations<\/h2>\n\n\n\n
                                                                                                          Add an Existing Issue or PR<\/h3>\n\n\n\n
                                                                                                          mutation {\n  addProjectV2ItemById(\n    input: {\n      projectId: \"PROJECT_ID\"\n      contentId: \"ISSUE_OR_PR_NODE_ID\"\n    }\n  ) {\n    item {\n      id\n    }\n  }\n}\n<\/code><\/pre>\n\n\n\n
                                                                                                          Important:<\/strong> adding an item and changing its project field value are separate operations. First add the item; then use the returned project-item ID in the update mutation.<\/p>\n\n\n\n
                                                                                                          Update a Text Field<\/h3>\n\n\n\n
                                                                                                          mutation {\n  updateProjectV2ItemFieldValue(\n    input: {\n      projectId: \"PROJECT_ID\"\n      itemId: \"PROJECT_ITEM_ID\"\n      fieldId: \"FIELD_ID\"\n      value: { text: \"Payments workstream\" }\n    }\n  ) {\n    projectV2Item {\n      id\n    }\n  }\n}\n<\/code><\/pre>\n\n\n\n
                                                                                                          Update a Number Field<\/h3>\n\n\n\n
                                                                                                          mutation {\n  updateProjectV2ItemFieldValue(\n    input: {\n      projectId: \"PROJECT_ID\"\n      itemId: \"PROJECT_ITEM_ID\"\n      fieldId: \"ESTIMATE_FIELD_ID\"\n      value: { number: 5 }\n    }\n  ) {\n    projectV2Item { id }\n  }\n}\n<\/code><\/pre>\n\n\n\n
                                                                                                          Update a Date Field<\/h3>\n\n\n\n
                                                                                                          mutation {\n  updateProjectV2ItemFieldValue(\n    input: {\n      projectId: \"PROJECT_ID\"\n      itemId: \"PROJECT_ITEM_ID\"\n      fieldId: \"TARGET_DATE_FIELD_ID\"\n      value: { date: \"2026-10-15\" }\n    }\n  ) {\n    projectV2Item { id }\n  }\n}\n<\/code><\/pre>\n\n\n\n
                                                                                                          Update a Single-Select Field<\/h3>\n\n\n\n
                                                                                                          Single-select fields use the option ID<\/strong>, not the display text.<\/p>\n\n\n\n
                                                                                                          mutation {\n  updateProjectV2ItemFieldValue(\n    input: {\n      projectId: \"PROJECT_ID\"\n      itemId: \"PROJECT_ITEM_ID\"\n      fieldId: \"PRIORITY_FIELD_ID\"\n      value: { singleSelectOptionId: \"P0_OPTION_ID\" }\n    }\n  ) {\n    projectV2Item { id }\n  }\n}\n<\/code><\/pre>\n\n\n\n
                                                                                                          Update an Iteration Field<\/h3>\n\n\n\n
                                                                                                          mutation {\n  updateProjectV2ItemFieldValue(\n    input: {\n      projectId: \"PROJECT_ID\"\n      itemId: \"PROJECT_ITEM_ID\"\n      fieldId: \"ITERATION_FIELD_ID\"\n      value: { iterationId: \"ITERATION_ID\" }\n    }\n  ) {\n    projectV2Item { id }\n  }\n}\n<\/code><\/pre>\n\n\n\n
                                                                                                          Clear a Field Value<\/h3>\n\n\n\n
                                                                                                          mutation {\n  clearProjectV2ItemFieldValue(\n    input: {\n      projectId: \"PROJECT_ID\"\n      itemId: \"PROJECT_ITEM_ID\"\n      fieldId: \"FIELD_ID\"\n    }\n  ) {\n    projectV2Item { id }\n  }\n}\n<\/code><\/pre>\n\n\n\n
                                                                                                          Project Field vs Issue\/PR Metadata<\/h3>\n\n\n\n
                                                                                                          updateProjectV2ItemFieldValue<\/code> is for project-item fields. It does not<\/strong> replace issue\/PR mutations for native metadata such as Assignees, Labels, Milestone, or Repository.<\/p>\n\n\n\n
                                                                                                          flowchart TD\n    A[Need to change a value] --> B{Where does the value live?}\n    B -->|Project field| C[updateProjectV2ItemFieldValue]\n    B -->|Issue \/ PR property| D[Issue \/ PR GraphQL mutation]\n    C --> E[Project item metadata]\n    D --> F[Canonical Issue \/ PR metadata]\n<\/code><\/pre>\n\n\n\n
                                                                                                          30.5 Project Field Mutations<\/h2>\n\n\n\n
                                                                                                          A project automation may create or update custom fields, but treat schema changes like application schema changes: review them, name fields consistently, and avoid creating duplicates.<\/p>\n\n\n\n
                                                                                                          Typical field mutation lifecycle:<\/p>\n\n\n\n
                                                                                                          createProjectV2Field\n       |\n       v\nupdateProjectV2Field\n       |\n       v\ndeleteProjectV2Field\n<\/code><\/pre>\n\n\n\n
                                                                                                          Before deleting a field, understand the reporting and automation impact because its values disappear with the field.<\/p>\n\n\n\n
                                                                                                          30.6 Linking APIs<\/h2>\n\n\n\n
                                                                                                          Projects can be linked to repositories and teams for discoverability. API automation can manage these relationships for standardized project provisioning.<\/p>\n\n\n\n
                                                                                                          Example use case:<\/p>\n\n\n\n
                                                                                                          Create project template copy\n        |\n        +--> Link web repository\n        +--> Link api repository\n        +--> Link infra repository\n        +--> Link platform team\n<\/code><\/pre>\n\n\n\n
                                                                                                          30.7 Template APIs<\/h2>\n\n\n\n
                                                                                                          At organization scale, template-related API operations are useful when you provision many consistent projects. Template governance should still happen at the organizational level; API automation should not become an excuse to create hundreds of nearly identical but unmanaged projects.<\/p>\n\n\n\n
                                                                                                          \n\n\n\n
                                                                                                          31. ADVANCED \u2014 REST API for Projects<\/h1>\n\n\n\n
                                                                                                          Current GitHub REST documentation includes Projects endpoints for projects, items, draft items, fields, and views. This is important because older tutorials often state that current Projects are \u201cGraphQL only.\u201d That statement is no longer generally correct.<\/p>\n\n\n\n
                                                                                                          \n
                                                                                                          REST support is evolving. Verify the endpoint-specific token requirements, API version, and object support before standardizing production automation.<\/p>\n<\/blockquote>\n\n\n\n
                                                                                                          31.1 Project Endpoints<\/h2>\n\n\n\n
                                                                                                          REST endpoints support operations around user and organization projects, including listing and retrieving projects.<\/p>\n\n\n\n
                                                                                                          A generic authenticated request pattern is:<\/p>\n\n\n\n
                                                                                                          curl --request GET \\\n  --url 'https:\/\/api.github.com\/ORG_OR_USER_PROJECT_ENDPOINT' \\\n  --header 'Accept: application\/vnd.github+json' \\\n  --header 'Authorization: Bearer YOUR_TOKEN' \\\n  --header 'X-GitHub-Api-Version: 2026-03-10'\n<\/code><\/pre>\n\n\n\n
                                                                                                          Do not copy an endpoint path from an old blog without checking the current REST documentation; Projects REST paths and supported operations have changed over time.<\/p>\n\n\n\n
                                                                                                          31.2 Item Endpoints<\/h2>\n\n\n\n
                                                                                                          The REST Projects API includes operations for project items, such as listing, adding, retrieving, updating, deleting, and view-oriented item retrieval where supported.<\/p>\n\n\n\n
                                                                                                          REST item automation is useful when:<\/p>\n\n\n\n
                                                                                                            \n
                                                                                                          • your integration is already REST-first;<\/li>\n\n\n\n
                                                                                                          • the operation maps cleanly to a documented REST endpoint;<\/li>\n\n\n\n
                                                                                                          • your security platform manages fine-grained REST permissions more easily.<\/li>\n<\/ul>\n\n\n\n
                                                                                                            GraphQL remains attractive when you need many connected Project objects in one response.<\/p>\n\n\n\n
                                                                                                            31.3 Draft Item Endpoints<\/h2>\n\n\n\n
                                                                                                            Draft items can be created in current Projects through REST endpoints where documented for the relevant project owner type.<\/p>\n\n\n\n
                                                                                                            Drafts are useful for planning before deciding which repository should own the eventual issue.<\/p>\n\n\n\n
                                                                                                            flowchart LR\n    A[Portfolio idea] --> B[Draft item]\n    B --> C{Ready for engineering?}\n    C -->|No| B\n    C -->|Yes| D[Convert\/create repository issue]\n<\/code><\/pre>\n\n\n\n
                                                                                                            31.4 Field Endpoints<\/h2>\n\n\n\n
                                                                                                            REST field endpoints can expose project field information and supported field-management operations. Be careful to distinguish:<\/p>\n\n\n\n
                                                                                                              \n
                                                                                                            • project custom fields;<\/li>\n\n\n\n
                                                                                                            • GitHub-provided Project fields;<\/li>\n\n\n\n
                                                                                                            • issue fields owned by the organization;<\/li>\n\n\n\n
                                                                                                            • native issue\/PR metadata.<\/li>\n<\/ul>\n\n\n\n
                                                                                                              They can look similar in a table but have different ownership and mutation rules.<\/p>\n\n\n\n
                                                                                                              31.5 View Endpoints<\/h2>\n\n\n\n
                                                                                                              Current REST documentation also includes Project view operations. Views are configuration, not copies of project data: an item belongs to the project and can appear in many views.<\/p>\n\n\n\n
                                                                                                              REST vs GraphQL Decision Table<\/h3>\n\n\n\n
                                                                                                              Need<\/th>Prefer<\/th><\/tr><\/thead>
                                                                                                              Simple documented CRUD endpoint<\/td>REST<\/td><\/tr>
                                                                                                              Rich nested Project object discovery<\/td>GraphQL<\/td><\/tr>
                                                                                                              Existing REST enterprise integration<\/td>REST<\/td><\/tr>
                                                                                                              Need exact ProjectV2 node IDs\/field configuration in one query<\/td>GraphQL<\/td><\/tr>
                                                                                                              Shell-first admin task<\/td>gh project<\/code><\/td><\/tr>
                                                                                                              Event-driven repository automation<\/td>Actions + CLI\/API<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                              \n\n\n\n
                                                                                                              32. ADVANCED \u2014 GitHub CLI and Projects<\/h1>\n\n\n\n
                                                                                                              GitHub CLI provides a dedicated gh project<\/code> command family, making it the simplest automation layer for many administrator and developer workflows.<\/p>\n\n\n\n
                                                                                                              32.1 Authentication<\/h2>\n\n\n\n
                                                                                                              Check your current authentication:<\/p>\n\n\n\n
                                                                                                              gh auth status\n<\/code><\/pre>\n\n\n\n
                                                                                                              Add the minimum classic-token Projects scope used by gh project<\/code>:<\/p>\n\n\n\n
                                                                                                              gh auth refresh -s project\n<\/code><\/pre>\n\n\n\n
                                                                                                              For read-only API scripts, GitHub’s GraphQL Projects documentation also documents read:project<\/code>; the gh project<\/code> command family itself states project<\/code> as its minimum required scope.<\/p>\n\n\n\n
                                                                                                              32.2 Discover Projects<\/h2>\n\n\n\n
                                                                                                              # List organization projects<\/em>\ngh project list --owner acme-corp\n\n# Include closed projects<\/em>\ngh project list --owner acme-corp --closed\n\n# View project 7 in the browser<\/em>\ngh project view 7 --owner acme-corp --web\n<\/code><\/pre>\n\n\n\n
                                                                                                              32.3 Create and Edit a Project<\/h2>\n\n\n\n
                                                                                                              gh project create \\\n  --owner acme-corp \\\n  --title 'Acme Platform Delivery'\n<\/code><\/pre>\n\n\n\n
                                                                                                              gh project edit 7 \\\n  --owner acme-corp \\\n  --description 'Cross-repository platform delivery' \\\n  --visibility PRIVATE\n<\/code><\/pre>\n\n\n\n
                                                                                                              32.4 Fields<\/h2>\n\n\n\n
                                                                                                              List fields:<\/p>\n\n\n\n
                                                                                                              gh project field-list 7 --owner acme-corp\n<\/code><\/pre>\n\n\n\n
                                                                                                              Create a number field:<\/p>\n\n\n\n
                                                                                                              gh project field-create 7 \\\n  --owner acme-corp \\\n  --name 'Estimate' \\\n  --data-type NUMBER\n<\/code><\/pre>\n\n\n\n
                                                                                                              Create a single-select field:<\/p>\n\n\n\n
                                                                                                              gh project field-create 7 \\\n  --owner acme-corp \\\n  --name 'Priority' \\\n  --data-type SINGLE_SELECT \\\n  --single-select-options 'P0,P1,P2,P3'\n<\/code><\/pre>\n\n\n\n
                                                                                                              At the time of this guide, gh project field-create<\/code> advertises TEXT<\/code>, SINGLE_SELECT<\/code>, DATE<\/code>, and NUMBER<\/code>. Do not assume every UI field type can be created with that CLI command.<\/p>\n\n\n\n
                                                                                                              32.5 Items<\/h2>\n\n\n\n
                                                                                                              Add an issue:<\/p>\n\n\n\n
                                                                                                              gh project item-add 7 \\\n  --owner acme-corp \\\n  --url 'https:\/\/github.com\/acme-corp\/api\/issues\/42'\n<\/code><\/pre>\n\n\n\n
                                                                                                              Create a draft item:<\/p>\n\n\n\n
                                                                                                              gh project item-create 7 \\\n  --owner acme-corp \\\n  --title 'Evaluate next authentication provider' \\\n  --body 'Discovery item for Q4 planning.'\n<\/code><\/pre>\n\n\n\n
                                                                                                              List items using Project filter syntax:<\/p>\n\n\n\n
                                                                                                              gh project item-list 7 \\\n  --owner acme-corp \\\n  --query 'assignee:@me -status:Done'\n<\/code><\/pre>\n\n\n\n
                                                                                                              Update a field by friendly names:<\/p>\n\n\n\n
                                                                                                              gh project item-edit 7 \\\n  --owner acme-corp \\\n  --url 'https:\/\/github.com\/acme-corp\/api\/issues\/42' \\\n  --field 'Status' \\\n  --value 'In Progress'\n<\/code><\/pre>\n\n\n\n
                                                                                                              Update using machine-friendly IDs:<\/p>\n\n\n\n
                                                                                                              gh project item-edit \\\n  --id 'PROJECT_ITEM_ID' \\\n  --project-id 'PROJECT_ID' \\\n  --field-id 'ESTIMATE_FIELD_ID' \\\n  --number 5\n<\/code><\/pre>\n\n\n\n
                                                                                                              Clear a field:<\/p>\n\n\n\n
                                                                                                              gh project item-edit \\\n  --id 'PROJECT_ITEM_ID' \\\n  --project-id 'PROJECT_ID' \\\n  --field-id 'FIELD_ID' \\\n  --clear\n<\/code><\/pre>\n\n\n\n
                                                                                                              Archive an item:<\/p>\n\n\n\n
                                                                                                              gh project item-archive 7 \\\n  --owner acme-corp \\\n  --id 'PROJECT_ITEM_ID'\n<\/code><\/pre>\n\n\n\n
                                                                                                              32.6 Repository and Team Linking<\/h2>\n\n\n\n
                                                                                                              # Link to a repository<\/em>\ngh project link 7 \\\n  --owner acme-corp \\\n  --repo acme-corp\/api\n\n# Link to a team<\/em>\ngh project link 7 \\\n  --owner acme-corp \\\n  --team platform\n<\/code><\/pre>\n\n\n\n
                                                                                                              32.7 Scripted Project Management<\/h2>\n\n\n\n
                                                                                                              A common script discovers IDs once, then updates many items:<\/p>\n\n\n\n
                                                                                                              PROJECT_ID=$(gh project view 7 --owner acme-corp --format json --jq '.id')\n\nSTATUS_FIELD_ID=$(gh project field-list 7 \\\n  --owner acme-corp \\\n  --format json \\\n  --jq '.fields[] | select(.name == \"Status\") | .id')\n\nprintf 'Project: %s\\nStatus field: %s\\n' \"$PROJECT_ID\" \"$STATUS_FIELD_ID\"\n<\/code><\/pre>\n\n\n\n
                                                                                                              For reliable production scripts:<\/p>\n\n\n\n
                                                                                                                \n
                                                                                                              • use JSON output instead of parsing formatted tables;<\/li>\n\n\n\n
                                                                                                              • fail when IDs are missing or duplicated;<\/li>\n\n\n\n
                                                                                                              • quote shell variables;<\/li>\n\n\n\n
                                                                                                              • make operations idempotent;<\/li>\n\n\n\n
                                                                                                              • log identifiers, not credentials.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                \n\n\n\n
                                                                                                                33. ADVANCED \u2014 GitHub Apps and Projects<\/h1>\n\n\n\n
                                                                                                                A GitHub App is usually the strongest foundation for organization-owned automation because it separates the automation identity from an employee account and can use short-lived installation access tokens.<\/p>\n\n\n\n
                                                                                                                33.1 Authentication Model<\/h2>\n\n\n\n
                                                                                                                sequenceDiagram\n    participant S as Automation Service\n    participant A as GitHub App\n    participant G as GitHub\n    participant P as Project API\n\n    S->>A: Create signed app JWT\n    A->>G: Request installation token\n    G-->>A: Short-lived installation token\n    A-->>S: Token\n    S->>P: Call Projects API\n    P-->>S: Result\n<\/code><\/pre>\n\n\n\n
                                                                                                                33.2 Projects Permissions<\/h2>\n\n\n\n
                                                                                                                When designing the App, grant only the Projects permissions and related repository\/organization permissions required by the operation.<\/p>\n\n\n\n
                                                                                                                Examples:<\/p>\n\n\n\n
                                                                                                                Read dashboard integration\n  -> Project read permission\n\nProject field automation\n  -> Project write permission\n\nAutomation also labels issues\n  -> Add the corresponding Issues permission\n<\/code><\/pre>\n\n\n\n
                                                                                                                Project access does not magically grant permission to all private repository contents referenced by project items. Permission design must consider both the project object<\/strong> and the underlying issue\/PR repositories<\/strong>.<\/p>\n\n\n\n
                                                                                                                33.3 Installation Access Tokens<\/h2>\n\n\n\n
                                                                                                                Benefits include:<\/p>\n\n\n\n
                                                                                                                  \n
                                                                                                                • short lifetime;<\/li>\n\n\n\n
                                                                                                                • revocable App installation;<\/li>\n\n\n\n
                                                                                                                • organization-controlled identity;<\/li>\n\n\n\n
                                                                                                                • narrower permission model than a broad personal token;<\/li>\n\n\n\n
                                                                                                                • clearer audit ownership.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                  33.4 Integration Pattern<\/h2>\n\n\n\n
                                                                                                                  flowchart TD\n    A[Webhook \/ Schedule] --> B[GitHub App Service]\n    B --> C[Validate Event]\n    C --> D[Get Installation Token]\n    D --> E[Query Project]\n    E --> F[Apply Business Rule]\n    F --> G[Mutation \/ REST Update]\n    G --> H[Structured Audit Log]\n<\/code><\/pre>\n\n\n\n
                                                                                                                  Use a GitHub App when the automation is shared, business-critical, multi-repository, or expected to live longer than the individual who first built it.<\/p>\n\n\n\n
                                                                                                                  \n\n\n\n
                                                                                                                  34. ADVANCED \u2014 Project Security<\/h1>\n\n\n\n
                                                                                                                  Projects aggregate planning information from many repositories, so a project can expose organizational intent even when code remains protected.<\/p>\n\n\n\n
                                                                                                                  34.1 Threat Model<\/h2>\n\n\n\n
                                                                                                                  Potentially sensitive project data includes:<\/p>\n\n\n\n
                                                                                                                    \n
                                                                                                                  • unreleased product names;<\/li>\n\n\n\n
                                                                                                                  • vulnerability remediation plans;<\/li>\n\n\n\n
                                                                                                                  • incident follow-ups;<\/li>\n\n\n\n
                                                                                                                  • customer names;<\/li>\n\n\n\n
                                                                                                                  • acquisition\/partnership work;<\/li>\n\n\n\n
                                                                                                                  • internal priorities and dates;<\/li>\n\n\n\n
                                                                                                                  • staffing\/ownership metadata.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                    flowchart LR\n    A[Public\/Over-shared Project] --> B[Roadmap Exposure]\n    A --> C[Priority Exposure]\n    A --> D[Internal Naming Exposure]\n    E[Over-privileged Token] --> F[Unauthorized Updates]\n    G[Leaked Automation Secret] --> F\n<\/code><\/pre>\n\n\n\n
                                                                                                                    34.2 Least Privilege Checklist<\/h2>\n\n\n\n
                                                                                                                    Area<\/th>Secure default<\/th><\/tr><\/thead>
                                                                                                                    Visibility<\/td>Private unless public planning is intentional<\/td><\/tr>
                                                                                                                    Human access<\/td>Read for observers; Write only for editors<\/td><\/tr>
                                                                                                                    Admin<\/td>Small owner\/admin group<\/td><\/tr>
                                                                                                                    App\/token<\/td>Minimum Projects + repo permissions<\/td><\/tr>
                                                                                                                    Secrets<\/td>Store in GitHub encrypted secrets or approved secret manager<\/td><\/tr>
                                                                                                                    Logs<\/td>Never print tokens; avoid unnecessary sensitive payloads<\/td><\/tr>
                                                                                                                    Outside collaborators<\/td>Explicit review<\/td><\/tr>
                                                                                                                    Templates<\/td>Do not embed real confidential draft items<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                    34.3 Public Project Exposure<\/h2>\n\n\n\n
                                                                                                                    A public project can be viewable on the Internet, but a viewer still needs access to underlying private repository content to see those private items. Do not rely on that boundary as your only confidentiality control: project-level fields, draft issues, titles, documentation, or updates may themselves reveal sensitive planning data.<\/p>\n\n\n\n
                                                                                                                    34.4 Automation Credential Security<\/h2>\n\n\n\n
                                                                                                                    Prefer this order for organization automation:<\/p>\n\n\n\n
                                                                                                                    GitHub App installation token\n        >\nshort-lived or narrowly scoped managed token\n        >\nlong-lived personal credential\n<\/code><\/pre>\n\n\n\n
                                                                                                                    The final choice depends on the supported API and your organization’s authentication policy.<\/p>\n\n\n\n
                                                                                                                    Secret Handling Example<\/h3>\n\n\n\n
                                                                                                                    permissions:\n  contents: read\n\njobs:\n  project-update:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Run project automation\n        env:\n          GH_TOKEN: ${{ secrets.PROJECT_TOKEN }}\n        run: |\n          gh project item-list 7 --owner acme-corp --format json >\/tmp\/items.json\n          # Never: echo \"$GH_TOKEN\"\n<\/code><\/pre>\n\n\n\n
                                                                                                                    \n\n\n\n
                                                                                                                    35. ADVANCED \u2014 Organization Governance<\/h1>\n\n\n\n
                                                                                                                    Organization governance answers a different question from project administration:<\/p>\n\n\n\n
                                                                                                                    \n
                                                                                                                    How do we make many projects understandable and safe across teams?<\/p>\n<\/blockquote>\n\n\n\n
                                                                                                                    35.1 Governance Layers<\/h2>\n\n\n\n
                                                                                                                    flowchart TD\n    A[Organization Policy] --> B[Templates]\n    A --> C[Base Permissions]\n    A --> D[Issue Field Taxonomy]\n    A --> E[Visibility Rules]\n    B --> F[Team Projects]\n    C --> F\n    D --> F\n    E --> F\n    F --> G[Purpose-Specific Views]\n    F --> H[Automation]\n<\/code><\/pre>\n\n\n\n
                                                                                                                    35.2 Recommended Organization Standards<\/h2>\n\n\n\n
                                                                                                                    Governance area<\/th>Example standard<\/th><\/tr><\/thead>
                                                                                                                    Status<\/td>Backlog, Ready, In Progress, In Review, Done<\/td><\/tr>
                                                                                                                    Priority<\/td>P0, P1, P2, P3<\/td><\/tr>
                                                                                                                    Estimate<\/td>Numeric field with documented scale<\/td><\/tr>
                                                                                                                    Iteration<\/td>One named Sprint field per delivery project<\/td><\/tr>
                                                                                                                    Visibility<\/td>Private by default<\/td><\/tr>
                                                                                                                    Template<\/td>Approved Engineering Delivery template<\/td><\/tr>
                                                                                                                    Ownership<\/td>At least two project admins<\/td><\/tr>
                                                                                                                    Archive<\/td>Auto-archive stale completed items<\/td><\/tr>
                                                                                                                    README<\/td>Required operating rules<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                    35.3 Base Permissions<\/h2>\n\n\n\n
                                                                                                                    Set organization base project permission deliberately. Then layer explicit access through teams and named individuals.<\/p>\n\n\n\n
                                                                                                                    A simple model:<\/p>\n\n\n\n
                                                                                                                    Organization members: Read\nDelivery team:         Write\nProject maintainers:   Admin\nOutside collaborators: No access unless explicitly required\n<\/code><\/pre>\n\n\n\n
                                                                                                                    The correct policy depends on how open internal planning is, but broad write\/admin access should be intentional rather than accidental.<\/p>\n\n\n\n
                                                                                                                    35.4 Project Creation and Templates<\/h2>\n\n\n\n
                                                                                                                    When many teams independently invent Status, Priority, and Sprint schemas, reporting becomes expensive. Organization templates should standardize the 80% common model while leaving room for team-specific views and a small number of local fields.<\/p>\n\n\n\n
                                                                                                                    35.5 Team and Outside-Collaborator Access<\/h2>\n\n\n\n
                                                                                                                    Review these separately:<\/p>\n\n\n\n
                                                                                                                      \n
                                                                                                                    • Can the person see the project?<\/li>\n\n\n\n
                                                                                                                    • Can the person edit project fields\/views?<\/li>\n\n\n\n
                                                                                                                    • Can the person see the underlying private issue\/PR?<\/li>\n\n\n\n
                                                                                                                    • Can the person administer the project?<\/li>\n<\/ul>\n\n\n\n
                                                                                                                      Those are not the same capability.<\/p>\n\n\n\n
                                                                                                                      \n\n\n\n
                                                                                                                      36. ADVANCED \u2014 Enterprise Governance<\/h1>\n\n\n\n
                                                                                                                      Enterprise governance sits above organization-level conventions and focuses on policy consistency, security boundaries, supportability, and feature availability across organizations.<\/p>\n\n\n\n
                                                                                                                      36.1 GitHub Enterprise Cloud vs GitHub Enterprise Server<\/h2>\n\n\n\n
                                                                                                                      Do not assume a GitHub.com tutorial maps one-for-one to every GitHub Enterprise Server (GHES) version.<\/p>\n\n\n\n
                                                                                                                      Always verify:<\/p>\n\n\n\n
                                                                                                                        \n
                                                                                                                      • whether the Projects feature exists in your GHES version;<\/li>\n\n\n\n
                                                                                                                      • the available API surface;<\/li>\n\n\n\n
                                                                                                                      • field\/workflow\/view support;<\/li>\n\n\n\n
                                                                                                                      • limits;<\/li>\n\n\n\n
                                                                                                                      • authentication behavior;<\/li>\n\n\n\n
                                                                                                                      • organization\/enterprise policy controls.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                        flowchart TD\n    A[Enterprise Standard] --> B[Organization A]\n    A --> C[Organization B]\n    A --> D[Organization C]\n    B --> E[Team Projects]\n    C --> F[Team Projects]\n    D --> G[Team Projects]\n<\/code><\/pre>\n\n\n\n
                                                                                                                        36.2 Enterprise Governance Questions<\/h2>\n\n\n\n
                                                                                                                        Question<\/th>Why it matters<\/th><\/tr><\/thead>
                                                                                                                        Who may create organization projects?<\/td>Prevent unmanaged sprawl<\/td><\/tr>
                                                                                                                        Which templates are approved?<\/td>Standardize planning models<\/td><\/tr>
                                                                                                                        What is the default visibility?<\/td>Protect roadmap metadata<\/td><\/tr>
                                                                                                                        Who can install automation Apps?<\/td>Control machine identities<\/td><\/tr>
                                                                                                                        Which token types are allowed?<\/td>Reduce credential risk<\/td><\/tr>
                                                                                                                        How long is completed project data retained?<\/td>Lifecycle\/compliance<\/td><\/tr>
                                                                                                                        Which fields must be standardized?<\/td>Portfolio reporting<\/td><\/tr>
                                                                                                                        What works on the deployed GHES version?<\/td>Avoid unsupported design<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                        36.3 Automation Policy<\/h2>\n\n\n\n
                                                                                                                        A mature enterprise separates automation into tiers:<\/p>\n\n\n\n
                                                                                                                        Tier 1  Built-in Project workflows\nTier 2  Repository GitHub Actions\nTier 3  Shared GitHub App \/ platform automation\nTier 4  External portfolio\/data platform integration\n<\/code><\/pre>\n\n\n\n
                                                                                                                        Use the lowest tier that meets the requirement. Every higher tier increases credential, maintenance, and observability responsibilities.<\/p>\n\n\n\n
                                                                                                                        \n\n\n\n
                                                                                                                        Part VI \u2014 ADVANCED PROJECT ARCHITECTURE & PLANNING<\/h1>\n\n\n\n
                                                                                                                        37. ADVANCED \u2014 Advanced Field Architecture<\/h1>\n\n\n\n
                                                                                                                        A field architecture is the vocabulary of your planning system. Good architecture lets people answer questions without creating a new field for every meeting.<\/p>\n\n\n\n
                                                                                                                        37.1 Shared Metadata Strategy<\/h2>\n\n\n\n
                                                                                                                        Start with questions, not fields:<\/p>\n\n\n\n
                                                                                                                        Question<\/th>Candidate field<\/th><\/tr><\/thead>
                                                                                                                        What stage is this in?<\/td>Status<\/td><\/tr>
                                                                                                                        How important is it?<\/td>Priority<\/td><\/tr>
                                                                                                                        How large is it?<\/td>Estimate \/ Effort<\/td><\/tr>
                                                                                                                        Who owns the workstream?<\/td>Team<\/td><\/tr>
                                                                                                                        What business area is affected?<\/td>Product Area<\/td><\/tr>
                                                                                                                        When will we work on it?<\/td>Sprint \/ Iteration<\/td><\/tr>
                                                                                                                        When should it finish?<\/td>Target Date<\/td><\/tr>
                                                                                                                        Which release carries it?<\/td>Release<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                        Recommended Core Model<\/h3>\n\n\n\n
                                                                                                                        Status       single-select \/ built-in Status\nPriority     single-select or organization issue field\nEstimate     number\nTeam         single-select or organization issue field\nWorkstream   single-select\nStart Date   date\nTarget Date  date\nSprint       iteration\nRelease      single-select\/text only if Milestone is not the right model\n<\/code><\/pre>\n\n\n\n
                                                                                                                        37.2 Status Taxonomy<\/h2>\n\n\n\n
                                                                                                                        Avoid statuses that encode multiple dimensions.<\/p>\n\n\n\n
                                                                                                                        Good:<\/p>\n\n\n\n
                                                                                                                        Backlog -> Ready -> In Progress -> In Review -> Done\n<\/code><\/pre>\n\n\n\n
                                                                                                                        Problematic:<\/p>\n\n\n\n
                                                                                                                        Backend P1 In Progress\nFrontend Blocked\nReady for Sprint 24\n<\/code><\/pre>\n\n\n\n
                                                                                                                        The problematic values mix team, priority, state, and iteration into one field.<\/p>\n\n\n\n
                                                                                                                        flowchart LR\n    A[Backlog] --> B[Ready]\n    B --> C[In Progress]\n    C --> D[In Review]\n    D --> E[Done]\n    C --> F[Blocked]\n    F --> C\n<\/code><\/pre>\n\n\n\n
                                                                                                                        Blocked<\/code> can be a Status when the team wants it to interrupt the flow, but for many organizations a separate blocker\/dependency signal is cleaner because an item may be both \u201cIn Progress\u201d and blocked.<\/p>\n\n\n\n
                                                                                                                        37.3 Priority Taxonomy<\/h2>\n\n\n\n
                                                                                                                        A four-value scheme is usually enough:<\/p>\n\n\n\n
                                                                                                                        Priority<\/th>Meaning<\/th><\/tr><\/thead>
                                                                                                                        P0<\/td>Immediate\/critical<\/td><\/tr>
                                                                                                                        P1<\/td>High<\/td><\/tr>
                                                                                                                        P2<\/td>Normal<\/td><\/tr>
                                                                                                                        P3<\/td>Low \/ opportunistic<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                        Document whether P0 represents business priority, operational severity, or both. If incidents already have a Severity field, do not make Priority secretly duplicate Severity.<\/p>\n\n\n\n
                                                                                                                        37.4 Effort Taxonomy<\/h2>\n\n\n\n
                                                                                                                        Two common models:<\/p>\n\n\n\n
                                                                                                                        Model A: Number field -> 1, 2, 3, 5, 8, 13\nModel B: Single-select -> XS, S, M, L, XL\n<\/code><\/pre>\n\n\n\n
                                                                                                                        Use number fields when you want sums\/capacity analysis. Use categorical sizes when precision would be false confidence.<\/p>\n\n\n\n
                                                                                                                        37.5 Team, Workstream and Product Area<\/h2>\n\n\n\n
                                                                                                                        These fields answer different questions:<\/p>\n\n\n\n
                                                                                                                        Team         = who owns it?\nWorkstream   = which delivery stream does it belong to?\nProduct Area = what part of the product does it affect?\n<\/code><\/pre>\n\n\n\n
                                                                                                                        Example:<\/p>\n\n\n\n
                                                                                                                        Item<\/th>Team<\/th>Workstream<\/th>Product Area<\/th><\/tr><\/thead>
                                                                                                                        Add passkey login<\/td>Identity<\/td>Authentication Modernization<\/td>Account<\/td><\/tr>
                                                                                                                        Rotate DB credentials<\/td>Platform<\/td>Security Hardening<\/td>Infrastructure<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                        37.6 Date Architecture<\/h2>\n\n\n\n
                                                                                                                        Use dates intentionally:<\/p>\n\n\n\n
                                                                                                                        Start Date  = planned start of meaningful work\nTarget Date = planned completion \/ delivery target\nDue Date    = only create separately if it means something materially different\n<\/code><\/pre>\n\n\n\n
                                                                                                                        Too many date fields create contradictory schedules.<\/p>\n\n\n\n
                                                                                                                        37.7 Sprint, Quarter and Release<\/h2>\n\n\n\n
                                                                                                                        Prefer GitHub’s Iteration<\/strong> field for recurring sprints. A quarter can be represented by dates, a single-select field, or a higher-level planning model depending on reporting needs.<\/p>\n\n\n\n
                                                                                                                        Do not use a single-select field named Sprint<\/code> if the team actually needs iteration arithmetic such as @current<\/code>, @next<\/code>, and configured iteration breaks.<\/p>\n\n\n\n
                                                                                                                        37.8 Organization Issue Fields vs Project Custom Fields<\/h2>\n\n\n\n
                                                                                                                        If a value should remain consistent wherever an issue appears in the organization, consider an organization-level issue field<\/strong>. If the value is specific to one project’s planning context, use a project field<\/strong>.<\/p>\n\n\n\n
                                                                                                                        flowchart TD\n    A[Need structured metadata] --> B{Should the value be canonical on the issue across projects?}\n    B -->|Yes| C[Organization issue field]\n    B -->|No| D[Project custom field]\n<\/code><\/pre>\n\n\n\n
                                                                                                                        A project can currently use up to 50 total fields<\/strong>, including system and issue fields, so field design is also a capacity decision.<\/p>\n\n\n\n
                                                                                                                        37.9 Field Naming Conventions<\/h2>\n\n\n\n
                                                                                                                        Prefer names that survive team changes:<\/p>\n\n\n\n
                                                                                                                        Priority          \u2713\nTarget Date       \u2713\nWorkstream        \u2713\nPlatform Priority \u2717 unless intentionally platform-specific\nRajesh Status     \u2717 person-specific taxonomy\nQ4 Sprint Name    \u2717 date encoded into schema\n<\/code><\/pre>\n\n\n\n
                                                                                                                        \n\n\n\n
                                                                                                                        38. ADVANCED \u2014 Work Breakdown and Hierarchy<\/h1>\n\n\n\n
                                                                                                                        GitHub Issues supports parent\/sub-issue relationships, allowing multiple levels of hierarchy. Projects can surface parent relationships and sub-issue progress for planning.<\/p>\n\n\n\n
                                                                                                                        38.1 Conceptual Hierarchy<\/h2>\n\n\n\n
                                                                                                                        Many teams use vocabulary like:<\/p>\n\n\n\n
                                                                                                                        Initiative\n  \u2514\u2500\u2500 Epic\n       \u2514\u2500\u2500 Feature \/ Story\n            \u2514\u2500\u2500 Task \/ Bug\n<\/code><\/pre>\n\n\n\n
                                                                                                                        GitHub does not require you to use those exact product-management words. Model the hierarchy with Issues and issue types that match your organization.<\/p>\n\n\n\n
                                                                                                                        flowchart TD\n    A[Initiative: Modernize Authentication] --> B[Epic: Passkeys]\n    A --> C[Epic: Session Security]\n    B --> D[Feature: WebAuthn enrollment]\n    B --> E[Feature: Recovery flow]\n    D --> F[Task: API endpoint]\n    D --> G[Task: UI enrollment]\n<\/code><\/pre>\n\n\n\n
                                                                                                                        38.2 Parent Issues and Sub-Issues<\/h2>\n\n\n\n
                                                                                                                        Use parent\/sub-issue relationships when:<\/p>\n\n\n\n
                                                                                                                          \n
                                                                                                                        • work has real decomposition;<\/li>\n\n\n\n
                                                                                                                        • progress at the parent matters;<\/li>\n\n\n\n
                                                                                                                        • child issues deserve separate ownership\/discussion;<\/li>\n\n\n\n
                                                                                                                        • the hierarchy should remain visible outside one Project.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                          Do not create child issues merely to mimic checklist lines.<\/p>\n\n\n\n
                                                                                                                          38.3 Sub-Issue Progress<\/h2>\n\n\n\n
                                                                                                                          Sub-issue progress gives a useful roll-up signal, but do not confuse item count with effort. Completing 8 tiny sub-issues out of 10 does not always mean the parent is 80% of the effort complete.<\/p>\n\n\n\n
                                                                                                                          38.4 Issue Types<\/h2>\n\n\n\n
                                                                                                                          Default issue types include concepts such as Task, Bug, and Feature, and organizations can define custom issue types. Use types to describe what the issue is<\/strong>, not where it currently sits in the workflow.<\/p>\n\n\n\n
                                                                                                                          Type:   Bug\nStatus: In Progress\nPriority: P1\n<\/code><\/pre>\n\n\n\n
                                                                                                                          These dimensions should remain independent.<\/p>\n\n\n\n
                                                                                                                          38.5 Dependencies<\/h2>\n\n\n\n
                                                                                                                          GitHub Issues also supports blocked by \/ blocking<\/strong> relationships.<\/p>\n\n\n\n
                                                                                                                          Example:<\/p>\n\n\n\n
                                                                                                                          flowchart LR\n    A[Database schema change] -->|blocks| B[API migration]\n    B -->|blocks| C[Frontend rollout]\n<\/code><\/pre>\n\n\n\n
                                                                                                                          Issue dependencies describe execution ordering; parent\/sub-issues describe decomposition. They are not interchangeable.<\/p>\n\n\n\n
                                                                                                                          38.6 Cross-Project Hierarchy<\/h2>\n\n\n\n
                                                                                                                          Because hierarchy lives on Issues, a parent and child can appear in different Projects. This is powerful for portfolio models, but establish clear ownership so two projects do not independently change the same canonical planning metadata.<\/p>\n\n\n\n
                                                                                                                          \n\n\n\n
                                                                                                                          39. ADVANCED \u2014 Capacity and Workload Planning<\/h1>\n\n\n\n
                                                                                                                          GitHub Projects gives you useful building blocks for capacity planning, but it is not a full workforce\/resource-planning suite. Use estimates and field sums as decision support, not as mathematical certainty.<\/p>\n\n\n\n
                                                                                                                          39.1 Basic Capacity Model<\/h2>\n\n\n\n
                                                                                                                          Sprint capacity = team's planned point\/effort budget\nCommitted load  = sum(Estimate) for current iteration\nRemaining room  = capacity - committed load\n<\/code><\/pre>\n\n\n\n
                                                                                                                          Example:<\/p>\n\n\n\n
                                                                                                                          Team<\/th>Capacity<\/th>Current Sprint Estimate<\/th>Signal<\/th><\/tr><\/thead>
                                                                                                                          Platform<\/td>34<\/td>31<\/td>Near capacity<\/td><\/tr>
                                                                                                                          API<\/td>40<\/td>46<\/td>Over plan<\/td><\/tr>
                                                                                                                          Web<\/td>32<\/td>25<\/td>Room remains<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                          39.2 Project Setup<\/h2>\n\n\n\n
                                                                                                                          Fields:\n  Iteration = Sprint\n  Number    = Estimate\n  Team      = owning team\n\nView:\n  Filter    = sprint:@current\n  Group by  = Team\n  Field sum = Estimate\n<\/code><\/pre>\n\n\n\n
                                                                                                                          flowchart LR\n    A[Estimated Backlog] --> B[Assign Current Iteration]\n    B --> C[Group by Team]\n    C --> D[Sum Estimate]\n    D --> E{Within Capacity?}\n    E -->|Yes| F[Commit]\n    E -->|No| G[De-scope \/ Rebalance]\n    G --> B\n<\/code><\/pre>\n\n\n\n
                                                                                                                          39.3 Assignee Workload<\/h2>\n\n\n\n
                                                                                                                          A workload view can group by Assignee and sum Estimate. Use it to spot obvious overload, not to rank individual productivity.<\/p>\n\n\n\n
                                                                                                                          Better question:<\/p>\n\n\n\n
                                                                                                                          \n
                                                                                                                          \u201cDoes one person own too much committed work?\u201d<\/p>\n<\/blockquote>\n\n\n\n
                                                                                                                          Poor question:<\/p>\n\n\n\n
                                                                                                                          \n
                                                                                                                          \u201cWho produced the most story points?\u201d<\/p>\n<\/blockquote>\n\n\n\n
                                                                                                                          39.4 Iteration Workload<\/h2>\n\n\n\n
                                                                                                                          Roadmap and table views can help compare upcoming iterations. Be careful with carry-over work: if unfinished work moves sprint-to-sprint, your historical data may tell a different story than the current field value alone.<\/p>\n\n\n\n
                                                                                                                          39.5 Capacity Anti-Patterns<\/h2>\n\n\n\n
                                                                                                                          Avoid:<\/p>\n\n\n\n
                                                                                                                            \n
                                                                                                                          • treating story points as hours;<\/li>\n\n\n\n
                                                                                                                          • comparing teams with different estimation scales;<\/li>\n\n\n\n
                                                                                                                          • overfilling sprints because the arithmetic fits;<\/li>\n\n\n\n
                                                                                                                          • counting unestimated work as zero effort;<\/li>\n\n\n\n
                                                                                                                          • using assignee totals as performance scores.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                            \n\n\n\n
                                                                                                                            40. ADVANCED \u2014 Portfolio and Program Management<\/h1>\n\n\n\n
                                                                                                                            An organization-level Project can act as a portfolio or program view across teams and repositories.<\/p>\n\n\n\n
                                                                                                                            40.1 Portfolio Data Model<\/h2>\n\n\n\n
                                                                                                                            Recommended fields:<\/p>\n\n\n\n
                                                                                                                            Strategic Initiative\nWorkstream\nOwning Team\nPriority\nHealth\nStart Date\nTarget Date\nQuarter\nRelease \/ Milestone\n<\/code><\/pre>\n\n\n\n
                                                                                                                            Use issue hierarchy to keep portfolio items at a useful level of abstraction.<\/p>\n\n\n\n
                                                                                                                            flowchart TD\n    A[Company Objective] --> B[Initiative: Identity Modernization]\n    A --> C[Initiative: Cost Reduction]\n    B --> D[Platform Epic]\n    B --> E[Web Epic]\n    B --> F[Mobile Epic]\n    D --> G[Delivery Issues in Repo]\n    E --> H[Delivery Issues in Repo]\n    F --> I[Delivery Issues in Repo]\n<\/code><\/pre>\n\n\n\n
                                                                                                                            40.2 Multi-Team Project<\/h2>\n\n\n\n
                                                                                                                            A single organization Project can include items from many repositories and teams. Useful views include:<\/p>\n\n\n\n
                                                                                                                            View<\/th>Layout<\/th>Filter \/ grouping<\/th><\/tr><\/thead>
                                                                                                                            Executive roadmap<\/td>Roadmap<\/td>Group by Strategic Initiative<\/td><\/tr>
                                                                                                                            Team delivery<\/td>Board<\/td>Slice\/Filter Team<\/td><\/tr>
                                                                                                                            Risks<\/td>Table<\/td>priority:P0,P1 -status:Done<\/code> plus risk metadata<\/td><\/tr>
                                                                                                                            Quarter plan<\/td>Roadmap<\/td>Target dates within quarter<\/td><\/tr>
                                                                                                                            Current execution<\/td>Board<\/td>sprint:@current<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                            40.3 Project Health<\/h2>\n\n\n\n
                                                                                                                            Portfolio-level health should be explicit through Project updates or a clearly governed health field on higher-level items.<\/p>\n\n\n\n
                                                                                                                            Avoid inferring \u201cgreen\u201d simply because many issues are closed. A project can complete many low-risk tasks and still miss the critical path.<\/p>\n\n\n\n
                                                                                                                            40.4 Cross-Project Coordination<\/h2>\n\n\n\n
                                                                                                                            Use separate team Projects when teams need distinct workflows\/access, and a portfolio Project when leadership needs a shared strategic view. Do not duplicate every delivery issue into every portfolio project by default.<\/p>\n\n\n\n
                                                                                                                            \n\n\n\n
                                                                                                                            41. ADVANCED \u2014 Advanced Roadmap Planning<\/h1>\n\n\n\n
                                                                                                                            Roadmap views become useful when they communicate decisions, not when they reproduce every task on a timeline.<\/p>\n\n\n\n
                                                                                                                            41.1 Long-Range Planning<\/h2>\n\n\n\n
                                                                                                                            A simple model:<\/p>\n\n\n\n
                                                                                                                            Now      -> current committed work\nNext     -> likely next work\nLater    -> direction with lower certainty\n<\/code><\/pre>\n\n\n\n
                                                                                                                            For date-oriented roadmaps, configure Start Date and Target Date fields and use quarter\/year zoom for higher-level planning.<\/p>\n\n\n\n
                                                                                                                            41.2 Grouping Strategies<\/h2>\n\n\n\n
                                                                                                                            Choose one grouping that answers the audience’s question:<\/p>\n\n\n\n
                                                                                                                            Group by Team       -> Who is delivering?\nGroup by Workstream -> What stream is progressing?\nGroup by Priority   -> What is strategically important?\n<\/code><\/pre>\n\n\n\n
                                                                                                                            41.3 Milestone and Iteration Markers<\/h2>\n\n\n\n
                                                                                                                            Markers add context to the timeline:<\/p>\n\n\n\n
                                                                                                                              \n
                                                                                                                            • release milestones;<\/li>\n\n\n\n
                                                                                                                            • sprint boundaries;<\/li>\n\n\n\n
                                                                                                                            • important dates;<\/li>\n\n\n\n
                                                                                                                            • item-specific date markers.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                              They help readers compare planned work with external commitments.<\/p>\n\n\n\n
                                                                                                                              41.4 Quarterly and Annual Planning<\/h2>\n\n\n\n
                                                                                                                              Example roadmap field set:<\/p>\n\n\n\n
                                                                                                                              Field<\/th>Purpose<\/th><\/tr><\/thead>
                                                                                                                              Start Date<\/td>Planned start<\/td><\/tr>
                                                                                                                              Target Date<\/td>Planned end<\/td><\/tr>
                                                                                                                              Team<\/td>Ownership<\/td><\/tr>
                                                                                                                              Priority<\/td>Strategic ordering<\/td><\/tr>
                                                                                                                              Milestone<\/td>Release marker<\/td><\/tr>
                                                                                                                              Workstream<\/td>Program grouping<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                              41.5 Dependencies on a Roadmap<\/h2>\n\n\n\n
                                                                                                                              GitHub Issues can represent blocked by<\/code> \/ blocking<\/code> dependencies. Treat these as execution relationships. Do not assume the Project roadmap behaves like a full Gantt product with automatically scheduled dependency connector lines and critical-path calculations.<\/p>\n\n\n\n
                                                                                                                              Use dependencies to answer:<\/p>\n\n\n\n
                                                                                                                              What cannot start yet?\nWhat work is holding another issue?\nWhich prerequisite must be watched?\n<\/code><\/pre>\n\n\n\n
                                                                                                                              \n\n\n\n
                                                                                                                              42. ADVANCED \u2014 Advanced Kanban Design<\/h1>\n\n\n\n
                                                                                                                              A board should make flow problems obvious within seconds.<\/p>\n\n\n\n
                                                                                                                              42.1 Workflow Columns<\/h2>\n\n\n\n
                                                                                                                              Example engineering flow:<\/p>\n\n\n\n
                                                                                                                              Backlog | Ready | In Progress | In Review | Ready to Deploy | Done\n<\/code><\/pre>\n\n\n\n
                                                                                                                              Do not add a column for every tiny activity. More columns mean more transition overhead and less signal.<\/p>\n\n\n\n
                                                                                                                              42.2 WIP Limits<\/h2>\n\n\n\n
                                                                                                                              A WIP limit communicates a desired maximum for a column. In Projects, treat the displayed limit as a planning signal<\/strong>, not a hard policy gate that prevents another card from entering the column.<\/p>\n\n\n\n
                                                                                                                              Example:<\/p>\n\n\n\n
                                                                                                                              In Progress: limit 6\nIn Review:   limit 4\n<\/code><\/pre>\n\n\n\n
                                                                                                                              If Review is constantly above its limit, the problem may be reviewer capacity rather than developer throughput.<\/p>\n\n\n\n
                                                                                                                              42.3 Swimlane-Style Grouping<\/h2>\n\n\n\n
                                                                                                                              Use board grouping to create horizontal sections:<\/p>\n\n\n\n
                                                                                                                              Columns: Status\nGroup:   Team\n<\/code><\/pre>\n\n\n\n
                                                                                                                              Conceptually:<\/p>\n\n\n\n
                                                                                                                                           Ready | In Progress | Review | Done\nPlatform       3          2           1       8\nAPI            4          3           2      11\nWeb            2          4           1       9\n<\/code><\/pre>\n\n\n\n
                                                                                                                              42.4 Purpose-Specific Boards<\/h2>\n\n\n\n
                                                                                                                              Board<\/th>Columns<\/th>Extra organization<\/th><\/tr><\/thead>
                                                                                                                              Sprint board<\/td>Status<\/td>Filter sprint:@current<\/code><\/td><\/tr>
                                                                                                                              Priority board<\/td>Priority<\/td>Group by Team<\/td><\/tr>
                                                                                                                              Release board<\/td>Status<\/td>Filter milestone\/release<\/td><\/tr>
                                                                                                                              Backlog board<\/td>Priority<\/td>Filter Status=Backlog\/Ready<\/td><\/tr>
                                                                                                                              Team board<\/td>Status<\/td>Filter specific Team<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                              42.5 Flow Optimization<\/h2>\n\n\n\n
                                                                                                                              Watch for:<\/p>\n\n\n\n
                                                                                                                                \n
                                                                                                                              • cards aging in one status;<\/li>\n\n\n\n
                                                                                                                              • review queues growing;<\/li>\n\n\n\n
                                                                                                                              • too much simultaneous work;<\/li>\n\n\n\n
                                                                                                                              • many unowned cards;<\/li>\n\n\n\n
                                                                                                                              • large batches entering Done only at sprint end.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                                A board is valuable because it exposes system behavior, not because moving cards is visually satisfying.<\/p>\n\n\n\n
                                                                                                                                \n\n\n\n
                                                                                                                                43. ADVANCED \u2014 Advanced View Architecture<\/h1>\n\n\n\n
                                                                                                                                A mature Project has one data model and several purpose-specific views.<\/p>\n\n\n\n
                                                                                                                                flowchart TD\n    A[One Project Data Set] --> B[Executive Roadmap]\n    A --> C[Engineering Sprint Board]\n    A --> D[Product Backlog]\n    A --> E[Team View]\n    A --> F[Personal Work]\n    A --> G[Risk View]\n    A --> H[Done \/ Archive View]\n<\/code><\/pre>\n\n\n\n
                                                                                                                                43.1 Executive Views<\/h2>\n\n\n\n
                                                                                                                                Prefer:<\/p>\n\n\n\n
                                                                                                                                  \n
                                                                                                                                • higher-level items;<\/li>\n\n\n\n
                                                                                                                                • roadmap layout;<\/li>\n\n\n\n
                                                                                                                                • initiative\/workstream grouping;<\/li>\n\n\n\n
                                                                                                                                • target dates and health;<\/li>\n\n\n\n
                                                                                                                                • minimal operational noise.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                                  43.2 Engineering Views<\/h2>\n\n\n\n
                                                                                                                                  Prefer:<\/p>\n\n\n\n
                                                                                                                                    \n
                                                                                                                                  • current iteration;<\/li>\n\n\n\n
                                                                                                                                  • status board;<\/li>\n\n\n\n
                                                                                                                                  • assignee and estimate visible;<\/li>\n\n\n\n
                                                                                                                                  • repository\/team context;<\/li>\n\n\n\n
                                                                                                                                  • PR\/review state where useful.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                                    43.3 Product Views<\/h2>\n\n\n\n
                                                                                                                                    Prefer:<\/p>\n\n\n\n
                                                                                                                                      \n
                                                                                                                                    • backlog and discovery items;<\/li>\n\n\n\n
                                                                                                                                    • issue type;<\/li>\n\n\n\n
                                                                                                                                    • priority;<\/li>\n\n\n\n
                                                                                                                                    • product area\/workstream;<\/li>\n\n\n\n
                                                                                                                                    • target release\/date.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                                      43.4 Personal Workload View<\/h2>\n\n\n\n
                                                                                                                                      Example filter:<\/p>\n\n\n\n
                                                                                                                                      assignee:@me -status:Done\n<\/code><\/pre>\n\n\n\n
                                                                                                                                      Then group by Status or Iteration.<\/p>\n\n\n\n
                                                                                                                                      43.5 Risk View<\/h2>\n\n\n\n
                                                                                                                                      Risk views should be rule-based where possible. Example concepts:<\/p>\n\n\n\n
                                                                                                                                      High priority + not Done\nPast target date\nBlocked work\nUnassigned committed items\nItems in current iteration without estimate\n<\/code><\/pre>\n\n\n\n
                                                                                                                                      Some require metadata that Projects does not calculate automatically; create only the minimum fields\/automation needed for meaningful risk detection.<\/p>\n\n\n\n
                                                                                                                                      43.6 Done\/Archive Views<\/h2>\n\n\n\n
                                                                                                                                      Completed work should remain discoverable without crowding delivery views. Use filters and auto-archive rather than deleting useful history.<\/p>\n\n\n\n
                                                                                                                                      \n\n\n\n
                                                                                                                                      44. ADVANCED \u2014 Reporting and Analytics Patterns<\/h1>\n\n\n\n
                                                                                                                                      Project reporting should answer a decision question.<\/p>\n\n\n\n
                                                                                                                                      44.1 Reporting Matrix<\/h2>\n\n\n\n
                                                                                                                                      Question<\/th>Useful view\/chart<\/th><\/tr><\/thead>
                                                                                                                                      Where is work stuck?<\/td>Status distribution + board<\/td><\/tr>
                                                                                                                                      Who\/which team owns work?<\/td>Group by Team\/Assignee<\/td><\/tr>
                                                                                                                                      Are we overcommitted?<\/td>Iteration filtered field sums<\/td><\/tr>
                                                                                                                                      What is high priority?<\/td>Priority distribution\/table<\/td><\/tr>
                                                                                                                                      Which repo carries load?<\/td>Group\/chart by Repository<\/td><\/tr>
                                                                                                                                      How much effort is planned?<\/td>Sum Estimate<\/td><\/tr>
                                                                                                                                      What changed strategically?<\/td>Project update history<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                                      44.2 Progress Dashboard Pattern<\/h2>\n\n\n\n
                                                                                                                                      flowchart LR\n    A[Project Fields] --> B[Saved Views]\n    A --> C[Insights Charts]\n    A --> D[Project Updates]\n    B --> E[Operational Decisions]\n    C --> E\n    D --> F[Stakeholder Communication]\n<\/code><\/pre>\n\n\n\n
                                                                                                                                      44.3 Delivery Reporting<\/h2>\n\n\n\n
                                                                                                                                      Avoid equating Done item count<\/code> with delivered value. Complement status charts with:<\/p>\n\n\n\n
                                                                                                                                        \n
                                                                                                                                      • target\/milestone outcomes;<\/li>\n\n\n\n
                                                                                                                                      • high-priority completion;<\/li>\n\n\n\n
                                                                                                                                      • blocked work;<\/li>\n\n\n\n
                                                                                                                                      • release\/deployment facts;<\/li>\n\n\n\n
                                                                                                                                      • qualitative Project updates.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                                        44.4 Historical Analytics<\/h2>\n\n\n\n
                                                                                                                                        Projects is primarily an operational planning tool. If you need long-term trend analysis, complex lead-time calculations, or enterprise BI, export\/API-sync project data into an analytics system rather than overloading Project charts.<\/p>\n\n\n\n
                                                                                                                                        \n\n\n\n
                                                                                                                                        45. ADVANCED \u2014 Cross-Repository Project Design<\/h1>\n\n\n\n
                                                                                                                                        One of current Projects’ strongest capabilities is planning across repositories.<\/p>\n\n\n\n
                                                                                                                                        45.1 Example Architecture<\/h2>\n\n\n\n
                                                                                                                                        flowchart TD\n    A[Organization Project: Acme Platform Delivery]\n    B[web repo]\n    C[api repo]\n    D[infra repo]\n    E[docs repo]\n\n    B --> A\n    C --> A\n    D --> A\n    E --> A\n<\/code><\/pre>\n\n\n\n
                                                                                                                                        45.2 Repository Field<\/h2>\n\n\n\n
                                                                                                                                        Use the built-in Repository metadata to:<\/p>\n\n\n\n
                                                                                                                                          \n
                                                                                                                                        • filter one component;<\/li>\n\n\n\n
                                                                                                                                        • group work by codebase;<\/li>\n\n\n\n
                                                                                                                                        • compare workload distribution;<\/li>\n\n\n\n
                                                                                                                                        • build repository-specific stakeholder views.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                                          Example filters:<\/p>\n\n\n\n
                                                                                                                                          repo:acme-corp\/web\nrepo:acme-corp\/api status:\"In Progress\"\n<\/code><\/pre>\n\n\n\n
                                                                                                                                          45.3 Auto-Add Across Repositories<\/h2>\n\n\n\n
                                                                                                                                          Use multiple built-in auto-add workflows, subject to your plan’s workflow limits, when items should enter the project based on repository-specific filters.<\/p>\n\n\n\n
                                                                                                                                          Example:<\/p>\n\n\n\n
                                                                                                                                          web   -> label:platform\napi   -> label:platform\ninfra -> label:platform\n<\/code><\/pre>\n\n\n\n
                                                                                                                                          If logic becomes complex or spans many organizations\/repositories, central App automation may be easier to govern than many duplicated Actions workflows.<\/p>\n\n\n\n
                                                                                                                                          45.4 Default Repository<\/h2>\n\n\n\n
                                                                                                                                          Set a default repository when project-created issues should normally land in one repository. In a genuinely cross-repository program, teach users to verify the destination repository rather than blindly accepting the default.<\/p>\n\n\n\n
                                                                                                                                          45.5 Design Rule<\/h2>\n\n\n\n
                                                                                                                                          Do not create one Project per repository merely because repositories are separate. Create Projects around planning boundaries<\/strong>: teams, programs, products, releases, or portfolios.<\/p>\n\n\n\n
                                                                                                                                          \n\n\n\n
                                                                                                                                          46. ADVANCED \u2014 Automation Architecture<\/h1>\n\n\n\n
                                                                                                                                          Automation should reduce manual bookkeeping while preserving clear ownership and predictable behavior.<\/p>\n\n\n\n
                                                                                                                                          46.1 Automation Layers<\/h2>\n\n\n\n
                                                                                                                                          flowchart TB\n    A[Built-in Project Workflows]\n    B[GitHub Actions]\n    C[GitHub CLI Scripts]\n    D[GraphQL \/ REST API]\n    E[GitHub App]\n    F[External Systems]\n\n    A --> G[GitHub Project]\n    B --> C\n    B --> D\n    C --> G\n    D --> G\n    E --> D\n    F --> E\n<\/code><\/pre>\n\n\n\n
                                                                                                                                          46.2 When to Use Which Layer<\/h2>\n\n\n\n
                                                                                                                                          Requirement<\/th>Best starting point<\/th><\/tr><\/thead>
                                                                                                                                          Set Done when issue closes<\/td>Built-in workflow<\/td><\/tr>
                                                                                                                                          Auto-add matching repo issues<\/td>Built-in auto-add<\/td><\/tr>
                                                                                                                                          One-off admin script<\/td>gh project<\/code><\/td><\/tr>
                                                                                                                                          Repository event + custom logic<\/td>GitHub Actions<\/td><\/tr>
                                                                                                                                          Rich object discovery\/update<\/td>GraphQL<\/td><\/tr>
                                                                                                                                          Existing REST integration<\/td>REST API<\/td><\/tr>
                                                                                                                                          Long-lived organization integration<\/td>GitHub App<\/td><\/tr>
                                                                                                                                          BI\/ITSM sync<\/td>App\/external service<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                                          46.3 Event-Driven vs Scheduled<\/h2>\n\n\n\n
                                                                                                                                          Event-driven:<\/p>\n\n\n\n
                                                                                                                                          Issue labeled -> update priority immediately\nPR merged     -> update release status immediately\n<\/code><\/pre>\n\n\n\n
                                                                                                                                          Scheduled:<\/p>\n\n\n\n
                                                                                                                                          Every day -> detect stale unowned work\nEvery week -> generate governance report\n<\/code><\/pre>\n\n\n\n
                                                                                                                                          Prefer events when GitHub already emits the fact you need. Use schedules for reconciliation and conditions that require scanning state.<\/p>\n\n\n\n
                                                                                                                                          46.4 Idempotency<\/h2>\n\n\n\n
                                                                                                                                          Every custom automation should be safe to run more than once.<\/p>\n\n\n\n
                                                                                                                                          Bad:<\/p>\n\n\n\n
                                                                                                                                          Every run creates another duplicate draft item.\n<\/code><\/pre>\n\n\n\n
                                                                                                                                          Good:<\/p>\n\n\n\n
                                                                                                                                          Find existing item -> compare desired value -> update only if needed.\n<\/code><\/pre>\n\n\n\n
                                                                                                                                          46.5 Observability<\/h2>\n\n\n\n
                                                                                                                                          For business-critical automation, record:<\/p>\n\n\n\n
                                                                                                                                            \n
                                                                                                                                          • event\/request ID;<\/li>\n\n\n\n
                                                                                                                                          • project\/item IDs;<\/li>\n\n\n\n
                                                                                                                                          • action attempted;<\/li>\n\n\n\n
                                                                                                                                          • result;<\/li>\n\n\n\n
                                                                                                                                          • non-secret error details;<\/li>\n\n\n\n
                                                                                                                                          • retry outcome.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                                            Do not make a planning system dependent on automation nobody can diagnose.<\/p>\n\n\n\n
                                                                                                                                            \n\n\n\n
                                                                                                                                            Part VII \u2014 ADVANCED INTEGRATIONS, ADMINISTRATION & REFERENCE<\/h1>\n\n\n\n
                                                                                                                                            47. ADVANCED \u2014 Project Integration with GitHub Issues<\/h1>\n\n\n\n
                                                                                                                                            Issues are the primary durable planning objects for most work tracked in Projects.<\/p>\n\n\n\n
                                                                                                                                            47.1 Issue Creation<\/h2>\n\n\n\n
                                                                                                                                            You can create an issue from a Project or create it in a repository and add it to the Project.<\/p>\n\n\n\n
                                                                                                                                            CLI example:<\/p>\n\n\n\n
                                                                                                                                            gh issue create \\\n  --repo acme-corp\/api \\\n  --title 'Add token rotation endpoint' \\\n  --body 'Implement the API required by the authentication rollout.' \\\n  --type Task \\\n  --project 'Acme Platform Delivery'\n<\/code><\/pre>\n\n\n\n
                                                                                                                                            When creating from Projects, select the correct destination repository\u2014especially in cross-repository projects.<\/p>\n\n\n\n
                                                                                                                                            47.2 Issue Metadata<\/h2>\n\n\n\n
                                                                                                                                            Useful native issue metadata includes:<\/p>\n\n\n\n
                                                                                                                                              \n
                                                                                                                                            • Assignees;<\/li>\n\n\n\n
                                                                                                                                            • Labels;<\/li>\n\n\n\n
                                                                                                                                            • Milestone;<\/li>\n\n\n\n
                                                                                                                                            • Issue Type;<\/li>\n\n\n\n
                                                                                                                                            • State \/ close reason;<\/li>\n\n\n\n
                                                                                                                                            • Parent\/sub-issue relationships;<\/li>\n\n\n\n
                                                                                                                                            • dependencies;<\/li>\n\n\n\n
                                                                                                                                            • organization issue fields where enabled.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                                              These are canonical issue properties rather than ordinary project-scoped custom fields.<\/p>\n\n\n\n
                                                                                                                                              47.3 Issue Type<\/h2>\n\n\n\n
                                                                                                                                              Use Issue Type to describe the nature of the work:<\/p>\n\n\n\n
                                                                                                                                              Bug\nFeature\nTask\nCustom organization types\n<\/code><\/pre>\n\n\n\n
                                                                                                                                              Do not duplicate this with a Project single-select field called Work Type<\/code> unless the two truly mean different things.<\/p>\n\n\n\n
                                                                                                                                              47.4 Parent Issues and Sub-Issues<\/h2>\n\n\n\n
                                                                                                                                              CLI examples:<\/p>\n\n\n\n
                                                                                                                                              # Create a child under parent issue 100<\/em>\ngh issue create \\\n  --repo acme-corp\/api \\\n  --title 'Implement WebAuthn challenge endpoint' \\\n  --parent 100\n<\/code><\/pre>\n\n\n\n
                                                                                                                                              # Add an existing issue as a sub-issue<\/em>\ngh issue edit 100 \\\n  --repo acme-corp\/api \\\n  --add-sub-issue 123\n<\/code><\/pre>\n\n\n\n
                                                                                                                                              Use the Project’s Parent issue and Sub-issue progress metadata to build hierarchy-oriented views.<\/p>\n\n\n\n
                                                                                                                                              47.5 Dependencies<\/h2>\n\n\n\n
                                                                                                                                              CLI examples:<\/p>\n\n\n\n
                                                                                                                                              # Issue 140 is blocked by issue 123<\/em>\ngh issue edit 140 \\\n  --repo acme-corp\/api \\\n  --add-blocked-by 123\n<\/code><\/pre>\n\n\n\n
                                                                                                                                              Dependencies answer ordering\/blocking<\/strong> questions; sub-issues answer decomposition<\/strong> questions.<\/p>\n\n\n\n
                                                                                                                                              47.6 Organization Issue Fields<\/h2>\n\n\n\n
                                                                                                                                              Organization issue fields are designed for consistent metadata across an organization’s repositories and projects. Their values live on the issue and remain consistent across Projects.<\/p>\n\n\n\n
                                                                                                                                              Use them for organization-wide concepts such as:<\/p>\n\n\n\n
                                                                                                                                              Priority\nEffort\nCustomer\nTarget date\nProduct area\n<\/code><\/pre>\n\n\n\n
                                                                                                                                              Project custom fields remain appropriate for project-local concepts.<\/p>\n\n\n\n
                                                                                                                                              Synchronization Model<\/h3>\n\n\n\n
                                                                                                                                              flowchart TD\n    A[Issue] --> B[Organization Issue Field Value]\n    B --> C[Project A]\n    B --> D[Project B]\n    A --> E[Project A Local Field]\n    A --> F[Project B Local Field]\n<\/code><\/pre>\n\n\n\n
                                                                                                                                              The organization field value is shared. Project-local values can differ by project.<\/p>\n\n\n\n
                                                                                                                                              \n\n\n\n
                                                                                                                                              48. ADVANCED \u2014 Project Integration with Pull Requests<\/h1>\n\n\n\n
                                                                                                                                              Pull requests can be project items, and Projects can surface PR-specific metadata to connect planning with code review.<\/p>\n\n\n\n
                                                                                                                                              48.1 PRs as Project Items<\/h2>\n\n\n\n
                                                                                                                                              A PR can be added directly:<\/p>\n\n\n\n
                                                                                                                                              gh project item-add 7 \\\n  --owner acme-corp \\\n  --url 'https:\/\/github.com\/acme-corp\/api\/pull\/88'\n<\/code><\/pre>\n\n\n\n
                                                                                                                                              Direct PR tracking is useful for:<\/p>\n\n\n\n
                                                                                                                                                \n
                                                                                                                                              • release readiness;<\/li>\n\n\n\n
                                                                                                                                              • review queues;<\/li>\n\n\n\n
                                                                                                                                              • migration programs;<\/li>\n\n\n\n
                                                                                                                                              • dependency upgrades;<\/li>\n\n\n\n
                                                                                                                                              • security remediation.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                                                48.2 PR State and Review Metadata<\/h2>\n\n\n\n
                                                                                                                                                Relevant metadata includes:<\/p>\n\n\n\n
                                                                                                                                                PR state: Open \/ Closed \/ Merged\nReviewers\nLinked pull requests\nReview status where exposed\nRepository\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                Issue + PR Relationship<\/h3>\n\n\n\n
                                                                                                                                                A useful model is:<\/p>\n\n\n\n
                                                                                                                                                flowchart LR\n    A[Issue: User-visible requirement] --> B[Linked PR]\n    B --> C[Review]\n    C --> D[Merge]\n    D --> E[Built-in workflow can mark project work Done]\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                Do not always add both an issue and its PR to the same delivery view. That can double-count work. Add PRs directly when the PR itself is the thing stakeholders need to track, or create a dedicated review\/release view.<\/p>\n\n\n\n
                                                                                                                                                48.3 PR Automation<\/h2>\n\n\n\n
                                                                                                                                                Typical rules:<\/p>\n\n\n\n
                                                                                                                                                PR opened             -> add to release project\nPR ready for review   -> set Status = In Review\nPR merged             -> built-in workflow sets Status = Done\nPR closed unmerged    -> apply team-specific handling\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                Prefer built-in merge\/close workflows where they meet the requirement.<\/p>\n\n\n\n
                                                                                                                                                48.4 Deployment and Release Tracking<\/h2>\n\n\n\n
                                                                                                                                                Projects can coordinate implementation metadata, but deployment truth usually comes from Actions\/deployment environments\/release systems. If you copy deployment state into a Project field, automate it from the source of truth rather than relying on manual updates.<\/p>\n\n\n\n
                                                                                                                                                \n\n\n\n
                                                                                                                                                49. ADVANCED \u2014 Project Integration with Milestones<\/h1>\n\n\n\n
                                                                                                                                                Milestones and Projects complement each other.<\/p>\n\n\n\n
                                                                                                                                                49.1 When Milestones Fit<\/h2>\n\n\n\n
                                                                                                                                                Milestones work well for a repository-oriented target such as:<\/p>\n\n\n\n
                                                                                                                                                v3.2 release\nPublic Beta\nSecurity Hardening Phase 1\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                Projects add richer planning around the work assigned to those milestones.<\/p>\n\n\n\n
                                                                                                                                                49.2 Useful Project Operations<\/h2>\n\n\n\n
                                                                                                                                                You can:<\/p>\n\n\n\n
                                                                                                                                                  \n
                                                                                                                                                • show the Milestone field;<\/li>\n\n\n\n
                                                                                                                                                • filter by milestone;<\/li>\n\n\n\n
                                                                                                                                                • group items by milestone;<\/li>\n\n\n\n
                                                                                                                                                • use milestone markers on roadmaps where supported;<\/li>\n\n\n\n
                                                                                                                                                • create release-specific views.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                                                  Example conceptual filter:<\/p>\n\n\n\n
                                                                                                                                                  milestone:\"v3.2\" -status:Done\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                  49.3 Milestone vs Release Custom Field<\/h2>\n\n\n\n
                                                                                                                                                  Prefer the native Milestone when repository milestones are already your release source of truth. Create a custom Release field when you need organization-level semantics that a repository milestone cannot represent cleanly.<\/p>\n\n\n\n
                                                                                                                                                  Avoid maintaining both manually with the same meaning.<\/p>\n\n\n\n
                                                                                                                                                  \n\n\n\n
                                                                                                                                                  50. ADVANCED \u2014 Project Integration with Teams<\/h1>\n\n\n\n
                                                                                                                                                  Teams provide a natural access and ownership boundary for organization Projects.<\/p>\n\n\n\n
                                                                                                                                                  50.1 Team Linking<\/h2>\n\n\n\n
                                                                                                                                                  Linking a Project to a team improves discoverability and gives the team access according to GitHub’s team\/project behavior.<\/p>\n\n\n\n
                                                                                                                                                  CLI example:<\/p>\n\n\n\n
                                                                                                                                                  gh project link 7 \\\n  --owner acme-corp \\\n  --team platform\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                  50.2 Team Visibility vs Team Ownership Field<\/h2>\n\n\n\n
                                                                                                                                                  These are different:<\/p>\n\n\n\n
                                                                                                                                                  Linked Team      = GitHub relationship\/discoverability\/access\nTeam field value = planning metadata on an item\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                  A project may be linked to the Platform team while individual items have Team = Web<\/code>, API<\/code>, or Platform<\/code>.<\/p>\n\n\n\n
                                                                                                                                                  50.3 Team-Based Views<\/h2>\n\n\n\n
                                                                                                                                                  Examples:<\/p>\n\n\n\n
                                                                                                                                                  View: Platform Delivery\nFilter: team:Platform        # if Team is a filterable field with this value\nLayout: Board\nColumns: Status\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                  For Project filter syntax, use the exact field name\/value exposed in your project rather than assuming a built-in team:<\/code> qualifier exists for your custom Team field.<\/p>\n\n\n\n
                                                                                                                                                  50.4 Team Workload<\/h2>\n\n\n\n
                                                                                                                                                  Group by Team and sum Estimate to support sprint\/program planning. Use capacity conversations to rebalance ownership, not to score teams.<\/p>\n\n\n\n
                                                                                                                                                  \n\n\n\n
                                                                                                                                                  51. ADVANCED \u2014 Project Integration with Repositories<\/h1>\n\n\n\n
                                                                                                                                                  Repositories remain the home of Issues and Pull Requests; Projects organize those objects across planning contexts.<\/p>\n\n\n\n
                                                                                                                                                  51.1 Repository Linking<\/h2>\n\n\n\n
                                                                                                                                                  A linked Project can surface from a repository’s Projects area, improving discoverability.<\/p>\n\n\n\n
                                                                                                                                                  gh project link 7 \\\n  --owner acme-corp \\\n  --repo acme-corp\/api\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                  51.2 Default Repository<\/h2>\n\n\n\n
                                                                                                                                                  A default repository streamlines creating issues from the Project. It is a convenience, not an ownership rule.<\/p>\n\n\n\n
                                                                                                                                                  51.3 Importing and Adding Repository Items<\/h2>\n\n\n\n
                                                                                                                                                  Common approaches:<\/p>\n\n\n\n
                                                                                                                                                  Repository import during project creation\nBulk add from repository\nSearch\/add individual issues and PRs\nAuto-add workflow\nCLI\/API automation\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                  51.4 Repository Filters<\/h2>\n\n\n\n
                                                                                                                                                  Examples:<\/p>\n\n\n\n
                                                                                                                                                  repo:acme-corp\/api\nrepo:acme-corp\/infra is:issue\nrepo:acme-corp\/web -status:Done\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                  51.5 Cross-Repository Project Rule<\/h2>\n\n\n\n
                                                                                                                                                  Repository boundaries should not force planning boundaries. A single product feature may require work in web<\/code>, api<\/code>, infra<\/code>, and docs<\/code>; one organization Project can show the complete delivery picture.<\/p>\n\n\n\n
                                                                                                                                                  \n\n\n\n
                                                                                                                                                  52. ADVANCED \u2014 Project Templates at Scale<\/h1>\n\n\n\n
                                                                                                                                                  Templates turn good project design into reusable organization infrastructure.<\/p>\n\n\n\n
                                                                                                                                                  52.1 Template Portfolio<\/h2>\n\n\n\n
                                                                                                                                                  A mature organization may maintain a small curated set:<\/p>\n\n\n\n
                                                                                                                                                  Template<\/th>Purpose<\/th><\/tr><\/thead>
                                                                                                                                                  Engineering Delivery<\/td>Standard backlog + sprint execution<\/td><\/tr>
                                                                                                                                                  Product Roadmap<\/td>Strategic roadmap planning<\/td><\/tr>
                                                                                                                                                  Release<\/td>Release readiness across repos<\/td><\/tr>
                                                                                                                                                  Bug Management<\/td>Severity\/priority triage<\/td><\/tr>
                                                                                                                                                  Platform Migration<\/td>Multi-repository migration<\/td><\/tr>
                                                                                                                                                  Program Portfolio<\/td>Initiative-level coordination<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                                                  Avoid dozens of near-identical templates.<\/p>\n\n\n\n
                                                                                                                                                  52.2 What to Standardize<\/h2>\n\n\n\n
                                                                                                                                                  A template should intentionally define:<\/p>\n\n\n\n
                                                                                                                                                    \n
                                                                                                                                                  • fields and option taxonomies;<\/li>\n\n\n\n
                                                                                                                                                  • views;<\/li>\n\n\n\n
                                                                                                                                                  • configured built-in workflows that can be copied;<\/li>\n\n\n\n
                                                                                                                                                  • insights\/charts;<\/li>\n\n\n\n
                                                                                                                                                  • README\/instructions;<\/li>\n\n\n\n
                                                                                                                                                  • optional safe example draft items.<\/li>\n<\/ul>\n\n\n\n
                                                                                                                                                    Remember that copied\/template projects do not necessarily carry every relationship or all automation configuration. In particular, design post-creation steps for repository\/team links, permissions, and auto-add workflows where needed.<\/p>\n\n\n\n
                                                                                                                                                    52.3 Recommended Templates<\/h2>\n\n\n\n
                                                                                                                                                    Organizations can curate a limited set of recommended templates so users start from approved patterns rather than inventing a project model each time.<\/p>\n\n\n\n
                                                                                                                                                    52.4 Template Versioning Strategy<\/h2>\n\n\n\n
                                                                                                                                                    GitHub project templates do not behave like a software package manager that automatically upgrades every project created from them.<\/p>\n\n\n\n
                                                                                                                                                    Use a lightweight governance model:<\/p>\n\n\n\n
                                                                                                                                                    Template README version: v3\nField standard: 2026-Q3\nOwner: Platform PMO\nChange log: link to governance repository\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                    When the template changes, decide whether existing Projects should migrate. Do not assume they inherit changes automatically.<\/p>\n\n\n\n
                                                                                                                                                    \n\n\n\n
                                                                                                                                                    53. ADVANCED \u2014 Project Administration<\/h1>\n\n\n\n
                                                                                                                                                    Project administration is the operating discipline that keeps a Project trustworthy after its initial setup.<\/p>\n\n\n\n
                                                                                                                                                    53.1 Administrative Areas<\/h2>\n\n\n\n
                                                                                                                                                    Area<\/th>Admin question<\/th><\/tr><\/thead>
                                                                                                                                                    Settings<\/td>Is the title\/description\/README current?<\/td><\/tr>
                                                                                                                                                    Visibility<\/td>Is public\/private still appropriate?<\/td><\/tr>
                                                                                                                                                    Access<\/td>Who has read\/write\/admin?<\/td><\/tr>
                                                                                                                                                    Fields<\/td>Are any duplicates or unused fields present?<\/td><\/tr>
                                                                                                                                                    Views<\/td>Are saved views purposeful and named?<\/td><\/tr>
                                                                                                                                                    Workflows<\/td>Are automations enabled and correct?<\/td><\/tr>
                                                                                                                                                    Insights<\/td>Do charts answer real questions?<\/td><\/tr>
                                                                                                                                                    Links<\/td>Are repositories\/teams still relevant?<\/td><\/tr>
                                                                                                                                                    Updates<\/td>Is project health communicated?<\/td><\/tr>
                                                                                                                                                    Lifecycle<\/td>Should the project be closed or deleted?<\/td><\/tr>
                                                                                                                                                    Export<\/td>Is external reporting\/recovery required?<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                                                    53.2 Monthly Admin Review<\/h2>\n\n\n\n
                                                                                                                                                    [ ] Remove obsolete collaborators\n[ ] Review public visibility\n[ ] Check stale auto-add rules\n[ ] Archive old completed items\n[ ] Remove unused fields\/views\n[ ] Validate template\/version conventions\n[ ] Review Project README\n[ ] Confirm at least two admins for important projects\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                    53.3 Close vs Delete<\/h2>\n\n\n\n
                                                                                                                                                    Close a Project when the work is complete but history remains useful. Delete only when the Project itself should no longer exist and organizational policy allows it.<\/p>\n\n\n\n
                                                                                                                                                    \n\n\n\n
                                                                                                                                                    54. ADVANCED \u2014 Project Data Model<\/h1>\n\n\n\n
                                                                                                                                                    Understanding the data model prevents many API and reporting mistakes.<\/p>\n\n\n\n
                                                                                                                                                    54.1 Conceptual Model<\/h2>\n\n\n\n
                                                                                                                                                    classDiagram\n    class ProjectV2 {\n      id\n      number\n      title\n      public\n      closed\n    }\n    class ProjectV2Item {\n      id\n      type\n    }\n    class Issue\n    class PullRequest\n    class DraftIssue\n    class ProjectField\n    class FieldValue\n    class View\n    class Workflow\n    class Insight\n    class StatusUpdate\n    class RepositoryLink\n    class TeamLink\n\n    ProjectV2 \"1\" --> \"many\" ProjectV2Item\n    ProjectV2Item --> Issue\n    ProjectV2Item --> PullRequest\n    ProjectV2Item --> DraftIssue\n    ProjectV2 \"1\" --> \"many\" ProjectField\n    ProjectV2Item \"1\" --> \"many\" FieldValue\n    ProjectV2 \"1\" --> \"many\" View\n    ProjectV2 \"1\" --> \"many\" Workflow\n    ProjectV2 \"1\" --> \"many\" Insight\n    ProjectV2 \"1\" --> \"many\" StatusUpdate\n    ProjectV2 --> RepositoryLink\n    ProjectV2 --> TeamLink\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                    54.2 Critical Distinctions<\/h2>\n\n\n\n
                                                                                                                                                    Content ID vs Project Item ID<\/h3>\n\n\n\n
                                                                                                                                                    When you add Issue #42<\/code> to a Project:<\/p>\n\n\n\n
                                                                                                                                                    Issue node ID          = identity of the issue\nProject item ID        = identity of its membership in this Project\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                    Field-value mutations target the project item ID<\/strong>, not simply the issue number.<\/p>\n\n\n\n
                                                                                                                                                    Project Number vs Node ID<\/h3>\n\n\n\n
                                                                                                                                                    Project number = human-facing URL\/reference\nProject node ID = API identity used in GraphQL mutations\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                    Field Configuration vs Field Value<\/h3>\n\n\n\n
                                                                                                                                                    Priority field          = schema\/configuration\nP1 option               = field option\nItem's Priority = P1    = field value\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                    Views Are Not Data Copies<\/h3>\n\n\n\n
                                                                                                                                                    A View contains presentation\/query configuration. Items and field values belong to the Project data model and can appear in multiple views.<\/p>\n\n\n\n
                                                                                                                                                    \n\n\n\n
                                                                                                                                                    55. ADVANCED \u2014 Project API Authentication and Permissions<\/h1>\n\n\n\n
                                                                                                                                                    Authentication is part of the API design, not a final deployment detail.<\/p>\n\n\n\n
                                                                                                                                                    55.1 Authentication Options<\/h2>\n\n\n\n
                                                                                                                                                    Method<\/th>Typical use<\/th><\/tr><\/thead>
                                                                                                                                                    GitHub CLI login<\/td>Human\/admin scripts<\/td><\/tr>
                                                                                                                                                    Classic PAT<\/td>GraphQL\/CLI where policy permits<\/td><\/tr>
                                                                                                                                                    Fine-grained PAT<\/td>REST endpoints with explicit permission support<\/td><\/tr>
                                                                                                                                                    GitHub App installation token<\/td>Organization production automation<\/td><\/tr>
                                                                                                                                                    GITHUB_TOKEN<\/code><\/td>Repository Actions; do not assume Project access<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                                                    55.2 GraphQL Projects Scopes<\/h2>\n\n\n\n
                                                                                                                                                    For classic PAT-based GraphQL Projects access, GitHub documents:<\/p>\n\n\n\n
                                                                                                                                                    read:project -> query\/read Projects\nproject      -> write\/mutate Projects\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                    The exact permissions for a GitHub App or fine-grained token should be selected from the current Projects permission model and the other resources your automation touches.<\/p>\n\n\n\n
                                                                                                                                                    55.3 Permission Matrix Example<\/h2>\n\n\n\n
                                                                                                                                                    Automation action<\/th>Project access<\/th>Possible additional access<\/th><\/tr><\/thead>
                                                                                                                                                    Read project items<\/td>Read<\/td>Underlying repo read if private content needed<\/td><\/tr>
                                                                                                                                                    Update custom field<\/td>Write<\/td>None beyond Project if no repo object modified<\/td><\/tr>
                                                                                                                                                    Add label to issue<\/td>Project + issue access as applicable<\/td>Issues write<\/td><\/tr>
                                                                                                                                                    Merge PR<\/td>Project access not enough<\/td>Pull requests\/contents as required<\/td><\/tr>
                                                                                                                                                    Read private repo item details<\/td>Project visibility not enough<\/td>Repository permission<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                                                    55.4 Least-Privilege Flow<\/h2>\n\n\n\n
                                                                                                                                                    flowchart TD\n    A[Define operation] --> B[List Project permission needed]\n    B --> C[List repository\/org resource permissions needed]\n    C --> D[Choose identity type]\n    D --> E[Issue shortest\/narrowest usable credential]\n    E --> F[Test denied operations too]\n    F --> G[Deploy and audit]\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                    55.5 Authentication Failure Checklist<\/h2>\n\n\n\n
                                                                                                                                                    When an API call fails:<\/p>\n\n\n\n
                                                                                                                                                    1. Is the token valid?\n2. Does it include Projects read\/write access?\n3. Is SSO authorization required and satisfied?\n4. Can the identity access the organization\/project?\n5. Can it access the underlying private repository item?\n6. Is the API endpoint supported by this token type?\n7. Is the API\/version header current for the REST endpoint?\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                    \n\n\n\n
                                                                                                                                                    56. ADVANCED \u2014 Project Limits and Constraints<\/h1>\n\n\n\n
                                                                                                                                                    Limits change over time and can differ between GitHub.com plans and GitHub Enterprise Server versions. Treat this section as a design checkpoint and verify GitHub’s current documentation before building near a boundary.<\/p>\n\n\n\n
                                                                                                                                                    56.1 High-Impact Current Limits<\/h2>\n\n\n\n
                                                                                                                                                    As verified for this guide:<\/p>\n\n\n\n
                                                                                                                                                    Resource<\/th>Current documented limit \/ rule<\/th><\/tr><\/thead>
                                                                                                                                                    Project items<\/td>Up to 50,000<\/strong> items across active views and archive<\/td><\/tr>
                                                                                                                                                    Total fields in a Project<\/td>Up to 50<\/strong>, including issue fields and system fields<\/td><\/tr>
                                                                                                                                                    Organization issue fields<\/td>Up to 25<\/strong> per organization<\/td><\/tr>
                                                                                                                                                    Single-select organization issue-field options<\/td>Up to 100<\/strong><\/td><\/tr>
                                                                                                                                                    Recommended organization templates<\/td>Up to 6<\/strong> recommended templates<\/td><\/tr>
                                                                                                                                                    Auto-add workflows \u2014 Free<\/td>1<\/strong><\/td><\/tr>
                                                                                                                                                    Auto-add workflows \u2014 Pro<\/td>5<\/strong><\/td><\/tr>
                                                                                                                                                    Auto-add workflows \u2014 Team<\/td>5<\/strong><\/td><\/tr>
                                                                                                                                                    Auto-add workflows \u2014 Enterprise Cloud<\/td>20<\/strong><\/td><\/tr>
                                                                                                                                                    Auto-add workflows \u2014 Enterprise Server<\/td>20<\/strong> (verify your GHES version)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                                                                                                                                                    56.2 Functional Constraints to Remember<\/h2>\n\n\n\n
                                                                                                                                                    Auto-Add Filter Subset<\/h3>\n\n\n\n
                                                                                                                                                    Auto-add does not accept every Project filter qualifier. Current supported categories include a subset such as:<\/p>\n\n\n\n
                                                                                                                                                    is:\nlabel:\nreason:\nassignee:\nno:\n<\/code><\/pre>\n\n\n\n
                                                                                                                                                    Design the rule in the UI and test it rather than assuming a complex saved-view filter can be pasted unchanged.<\/p>\n\n\n\n
                                                                                                                                                    Auto-Add Is Not Historical Backfill<\/h3>\n\n\n\n
                                                                                                                                                    Enabling an auto-add workflow does not automatically import all existing matching items merely because they already satisfy the filter. The workflow acts when items are created or updated and match the rule. Backfill existing work separately when required.<\/p>\n\n\n\n
                                                                                                                                                    Board WIP Limits Are Signals<\/h3>\n\n\n\n
                                                                                                                                                    Treat column limits as visible WIP guidance rather than enforcement that blocks card movement.<\/p>\n\n\n\n
                                                                                                                                                    API Rate Limits<\/h3>\n\n\n\n
                                                                                                                                                    GraphQL and REST calls are subject to GitHub rate limiting. Bulk automation should paginate, cache stable IDs where appropriate, avoid unnecessary polling, and handle retry\/rate-limit responses.<\/p>\n\n\n\n
                                                                                                                                                    Layout\/Field Restrictions<\/h3>\n\n\n\n
                                                                                                                                                    Not every field can drive every layout feature. Examples include:<\/p>\n\n\n\n