Repository navigation
Feature request: Add projects_v2_item trigger support #25336
Description
Feature Request
Summary
Add support for the projects_v2_item webhook event as a workflow trigger, enabling agentic workflows to run when issues (or PRs) are added to, edited on, or removed from a GitHub Projects board.
Motivation
Currently, there is no way to trigger an agentic workflow when an issue is added to a project. This is a common need for teams that use GitHub Projects as their intake funnel — for example:
- Automatic triage when a support escalation issue lands on a team board
- Ownership assessment when an issue is added to a shared project
- Field population (classification, priority, dates) as soon as an item appears
Today the workarounds are:
- Using
issues.labeledas a proxy trigger (requires a labeling step) - A scheduled orchestrator that polls the project board (adds latency)
- A traditional GitHub Actions workflow on
projects_v2_itemthat dispatches the agentic workflow viaworkflow_dispatch(extra plumbing)
Native support would eliminate all of these workarounds.
Proposed Trigger Syntax
on:
projects_v2_item:
types: [created, edited, deleted, archived, restored, converted]Or a simplified gh-aw shorthand:
on:
project_item:
types: [created]
project: "https://github.com/orgs/<ORG>/projects/<NUMBER>"Activity Types
GitHub already supports these activity types on the projects_v2_item webhook:
| Type | Description |
|---|---|
created |
Item added to the project |
edited |
Item field value changed |
deleted |
Item removed from the project |
archived |
Item archived |
restored |
Item restored from archive |
converted |
Item converted (e.g., draft → issue) |
Context Variables
It would be useful to expose context like:
${{ github.event.projects_v2_item.content_type }}(issue, PR, draft)${{ github.event.projects_v2_item.content_node_id }}- The issue/PR number and repository when the content type is an issue or PR
Use Case
We are building installable agentic workflows in github/identity-core for support escalation triage. Currently we rely on issues.labeled with a support-escalation label, but triggering directly on project board addition would be more natural and eliminate the labeling requirement.
Activity
pelikhan commentedon Apr 15, 2026
@johnpreed repo or org level project board?
pierre-pilette commentedon Jul 27, 2026
This feature is highly anticipated — it would greatly simplify integrations with product management tools like Linear.
@pelikhan To follow up on the earlier question: both repo-level and org-level project boards should be supported.
I hope this gets picked up soon, as it would meaningfully restore the organizational workflows we had with the legacy project format.
lukewar commentedon Jul 28, 2026
Sharing perspective based on work around Project Automation and Plan & Track.
This seems like a valuable gap to explore, especially if there are strong signals that teams want Actions-style triggers from Projects. At the same time, I think it needs product clarification up front so behavior is predictable.
Questions that seem important to pin down:
item_added, should this fire for every item in the project, or only issues and PRs associated with the current repo?From a Plan & Track lens, getting these semantics clear early will matter a lot for trust and operability. If demand is strong, this feels worth investing in, but defining scope and rules first will likely prevent confusion later.
pelikhan commentedon Oct 7, 2026
Feasibility: GitHub App or PAT
An event-driven integration is feasible through an external webhook receiver, but
projects_v2_itemis not a native GitHub Actions trigger. Adding it to the gh-aw schema would not make Actions run. The proposed workaround using a traditional Actions workflow withon: projects_v2_itemhas the same limitation.projects_v2_item, and host a webhook receiver. Use an installation token with repository Contents: write to dispatch to the target repository.reposcope. A PAT alone does not receive webhooks.read:projectfor project queries; additional access may be needed to resolve private issue/PR content. Polling adds latency and can miss intermediate changes.Scope: The documented event covers organization-owned Projects. Linking such a project to a repository does not turn it into a repository webhook. User-owned Projects are not covered by this event. Legacy Projects (classic) triggers are not substitutes for Projects v2.
Existing gh-aw support:
repository_dispatchis already supported inpkg/parser/schemas/main_workflow_schema.jsonand documented in the trigger reference. No new native trigger is needed for a bridge:The App bot name above is illustrative and must be replaced with the actual sender. PAT senders must satisfy
on.roles; App senders must be allowlisted withon.bots. Keep these authorization checks enabled. The compiled workflow must exist on the default branch.The receiver should validate the webhook HMAC signature, allowlist organization/project and destination repository, filter activity types and content types, deduplicate delivery IDs, and resolve issue/PR repository and number from the content node ID when required. Forward only a minimal, approved payload; context then lives under
github.event.client_payload, notgithub.event.projects_v2_item. Do not automatically forward private project fields or issue content into public workflow logs. Handle drafts, deletion, retries, and edits caused by the automation itself explicitly.Conclusion: Native trigger support is blocked by the Actions event model, not token choice. The smallest viable event-driven solution is an App/organization-webhook bridge to existing
repository_dispatch; implementing that requires a hosted receiver and an explicit routing/filtering contract. No compiler changes or live dispatches were made during this investigation.Public references:
This report uses public documentation and anonymized examples only; it contains no internal integration details, credentials, or private project data.
pelikhan commentedon Oct 7, 2026
Follow-up: could this live in
githubnext/gh-aw-cao?Yes. CAO is a suitable home for the webhook-to-workflow bridge, specifically its hosted server deployment—not the Actions-only deployment. This is feasible as an extension, not functionality already present.
Public code already provides signed webhook ingress and delivery deduplication, durable admission and queued workers, and installation-token authentication.
The current event parser handles workflow runs, issues, repository lifecycle, and installation events; it does not handle
projects_v2_item. Its existing intents collect evidence, rather than launch project-triggered campaigns. A project event therefore needs an explicit routing/dispatch capability, not just another collection event.The extension would need organization Projects-read permission and subscription, policy mapping approved projects/activity types/content repositories to approved campaigns, content-node resolution, and a retryable dispatch task. Keep dispatch credentials separate from the read-only collector: use a narrowly scoped App installation token (or PAT) with destination Contents-write for
repository_dispatch, and retain the receiving workflow bot/role checks. Project routing must be checked against policy even when an App can access the organization.Do not reuse repository-collection debounce as project-event semantics: different items and field changes must not be inadvertently collapsed. Handle redelivery, drafts/deletion, and automation-induced edit loops. Forward only approved minimal metadata; do not expose private project content in public Actions logs.
The Actions-only App profile explicitly disables webhooks and has no continuously listening receiver, so that profile would still require polling or a separate hosted service. Organization-owned Projects are the supported webhook scope, including those linked to repositories; user-owned projects are outside that event.
Recommendation: implement an opt-in project-event router in the CAO hosted service and reuse existing gh-aw dispatch triggers. No native
on: projects_v2_itemcompiler change is needed. Findings are based solely on public source; no credentials, deployment details, or private project data were inspected or disclosed.pelikhan commentedon Oct 7, 2026
A concrete follow-up would be to implement this as an opt-in project-event router in githubnext/gh-aw-cao, rather than add an unsupported native Actions trigger to gh-aw. CAO’s hosted server already has signed webhook ingress, delivery deduplication, and queued processing; it would need Projects v2 event handling plus policy-controlled campaign dispatch.
The integration should subscribe to organization-owned project events with Projects-read permission, filter approved projects and activity types, resolve issue/PR content, and dispatch through existing
repository_dispatchsupport. Keep dispatch credentials separate from the read-only collector, preserve receiving workflow bot/role authorization, and forward only minimal approved metadata so private project content cannot leak into public logs. A PAT can authenticate dispatch but cannot replace the webhook receiver.This would apply to the hosted CAO service. The Actions-only deployment would still require polling or an external receiver. Native
on: projects_v2_itemremains unavailable until GitHub Actions supports that event. No code changes have been made; this is a proposed implementation direction based on public sources.pelikhan commentedon Oct 7, 2026
Status (2026-10-07; Cross-repo dependency): The October 7 discussion identifies
githubnext/gh-aw-cao’s hosted service as a proposed home for an opt-in Projects v2 webhook router, sinceprojects_v2_itemis not a native Actions trigger. The next step is to define approved event routing and dispatch authorization in that repository; no implementation was reported.pelikhan commentedon Oct 16, 2026
Current-state refresher (2026-10-16): still relevant as an integration request, but not an ordinary missing gh-aw trigger. The current Actions event reference still does not list
projects_v2_itemas a workflow trigger. A Projects webhook existing does not makeon: projects_v2_itemexecutable in Actions, including in a traditional wrapper workflow.Current gh-aw already supports the
repository_dispatchtrigger, so the practical direction from the October 7 discussion remains a hosted webhook receiver/router that dispatches approved project events. Native trigger support remains dependent on the Actions platform; receiver scope, authorization, deduplication and dispatch policy are separate integration work.The earlier CAO proposal is a proposed implementation home, not evidence that a router shipped. This pass did not verify CAO's current implementation or exercise an event delivery, so that cross-repository status remains explicitly unconfirmed.
pelikhan commentedon Oct 22, 2026
Relevance check — 2026-10-22: keep open as a platform/integration dependency, not an implemented native trigger. Rechecked current public platform docs and live gh-aw
mainatffdd9c9efe6a.The Actions event reference still does not list
projects_v2_itemand explicitly warns that not all webhooks trigger workflows. The Projects item webhook is an organization-level event requiring organization Projects read permission for an App; linking that project to a repository does not make it a repository Actions event. Therefore the original workaround #3 (on: projects_v2_itemin an ordinary wrapper) is not executable trigger support.Current gh-aw already accepts
repository_dispatch. The earlier proposed CAO receiver is not established as shipped: at current public CAO revisioncf53719535fc, its collector parser has no Projects-item branch and defaults unrecognized events to ignore. This is evidence about that proposed ingress, not a claim to have tested every deployment.Next concrete step: define an opt-in hosted webhook-to-dispatch bridge (CAO or another receiver), covering signature verification, approved org/project/destination/activity policy, content-node resolution and draft/deleted items, deduplication/retries and self-edit loops, narrowly scoped dispatch authentication, receiving bot/role checks, and minimal private-data-safe
client_payload. Repository-dispatch workflows must exist on the default branch. Native syntax still depends on Actions adding the event; a bridge is a separate integration, not proof this request is fixed. No live event delivery or dispatch performed.pelikhan commentedon Oct 22, 2026
@johnpreed this event will be supported through the webhook gateway in central agentic ops