Bridging the Gap: How GitHub Project Views Can Boost Engineering KPIs and Automation

GitHub Projects provide powerful, visual ways to manage work, track progress, and organize tasks. For many teams, specific project views serve as critical queues for both human and automated processes. However, a recent discussion in the GitHub Community highlights a significant limitation: the inability to programmatically read the contents of a project view via any API. This gap creates challenges for automation, data integrity, and ultimately, the accurate tracking of engineering kpis.

The Core Problem: Views Without Contents

As detailed by MarkBennett in Discussion #206375, the ProjectV2View object in GitHub's API exposes a view's definition – its filters, layout, grouping, and sorting rules. However, it lacks an items connection, meaning there's no way to query what a specific view actually displays. Consider this GraphQL introspection:

{
  __type(name: "ProjectV2View") {
    fields {
      name
    }
  }
}

Which returns fields like:

configuration, createdAt, databaseId, fields, filter, fullDatabaseId, groupBy, groupByFields, id, layout, name, number, project, sortBy, sortByFields, updatedAt, verticalGroupBy, verticalGroupByFields, visibleFields

While these fields describe how a view is configured, none of them return the actual issues or pull requests that the view shows.

Why This Matters for Automation and KPIs

This API gap forces teams to re-implement view logic in their automation scripts. Instead of simply asking GitHub, "what does view X show?", scripts must perform a broad query for the entire project's items, then manually apply the view's filter logic using tools like jq. This leads to several critical issues:

• Drift and Silent Failures: The project's UI view and the automation's query become two independent definitions of the same queue. If a view's filter is updated in the UI, the automation's script must be manually updated to match. If not, drift occurs silently, leading to incorrect data or actions. MarkBennett reported this happening twice, with filters quietly losing qualifiers like is:open.
• Lossy Approximation: The filtering languages of GitHub Projects and external scripting tools (like jq) are not perfectly equivalent. Attempting to translate between them can result in lossy approximations that fail silently, making the manual duplication, despite its flaws, a more "honest" approach for now.
• Hindrance to Engineering KPIs: Reliable automation is key to gathering accurate data for engineering kpis. When the source of truth (GitHub Project views) cannot be consistently mirrored by automation, the integrity of metrics derived from these projects is compromised.

The Ask: An items Connection for Views

The primary request is straightforward: an items connection on ProjectV2View. This would allow queries to return exactly what a person sees in that view, with the view's filter, grouping, and sort applied server-side. Read-only access is all that's needed. A corresponding CLI command (gh project item-list --view) is also desired, dependent on this API enhancement.

Related Gaps and Further Improvements for this Git Tool

MarkBennett also highlighted several other areas for improvement within this git tool's project capabilities:

• Filter Parity: The absence of a "leaf-only" qualifier (e.g., "issues that have no sub-issues") means views cannot fully mirror automation that targets only actionable, non-parent issues.
• Incomplete Documentation and Silent Failures: Project filtering documentation is incomplete, and the UI silently accepts unrecognized qualifiers, ignoring them rather than rejecting them. This leads to filters matching more than intended, a direct cause of reported drift incidents. The ask is to complete the documentation and surface warnings for unrecognized qualifiers.
• Unauditable Workflows: ProjectV2Workflow exposes no configuration, making auto-add workflows that guard project membership unauditable by script.
• View Ordering Bug: ProjectV2.views(orderBy:) silently ignores the field parameter, preventing programmatic access to a view's tab position.

While the original discussion was closed by a bot due to not using a template, the points raised by MarkBennett remain highly relevant for developers seeking to build robust automation and derive accurate engineering kpis from their GitHub Projects. Direct API access to view contents is a crucial step towards seamless integration and improved developer productivity.