Now Available ✨ Use project status updates with GraphQL and webhooks

[github-staff]

Today's changelog brings you GraphQL and webhook support for project status updates and project custom field changes directly in the webhook event!

⚙️ Using GraphQL and webhooks with project status updates

Following our release earlier this year for project status updates, you can now interact with project status updates using GraphQL and webhooks. This unlocks new ways to automate how you provide and gather project status update information.

GraphQL

There is a new ProjectV2StatusUpdate GraphQL object to interact with project status updates, so you can view, create, update, and delete status updates.

Below is an example query to create a new project status update.

mutation {
  createProjectV2StatusUpdate(
    input: {projectId: "0123456", body: "We wrapped up our bug bash following the beta rollout. We're back on track for our GA date in August! 🚀", startDate: "2024-06-03", targetDate: "2024-08-09", status: ON_TRACK}
  ) {
    statusUpdate {
      id
      startDate
      targetDate
      body
      bodyHTML
      status
    }
  }
}

Webhooks

Project status updates are included in the new projects_v2_status_update webhook event, so you can understand and be notified when a new project status update is provided.

You must be subscribed to this event from the organization settings page to receive this information.

Below is an example of a webhook event.

{
    "action": "edited",
    "projects_v2_status_update": {
        "id": 32633,
        "node_id": "PVTSU_lADOBH2n9s4Ajp6VzX95",
        "project_node_id": "PVT_kwDOBH2n9s4Ajp6V",
        "creator": {
          ...
        },
        "body": "We've kicked off this project and are feeling confident in our rollout plan. More updates and demos to come next week!",
        "start_date": "2024-06-24",
        "target_date": "2024-08-16",
        "status": "ON_TRACK",
        "created_at": "2024-06-24T20:27:48Z",
        "updated_at": "2024-06-24T20:30:47Z"
    },
    "changes": {
        "body": {
            "from": "We're still planning this out and are kicking off soon.",
            "to": "We've kicked off this project and are feeling confident in our rollout plan. More updates and demos to come next week!"
        },
        "status": {
            "from": "INACTIVE",
            "to": "ON_TRACK"
        },
        "start_date": {
            "from": null,
            "to": "2024-06-24"
        },
        "target_date": {
            "from": null,
            "to": "2024-08-16"
        }
    },
    "organization": {
        ...
    },
    "sender": {
        ...
    }
}

➕ Using webhooks for project custom field changes

Project custom field changes are now included directly in the project_v2_item webhook event when a project item's fields are edited, removing the need to send an additional GraphQL query. This gives you the previous and current field values to understand how project fields change over time and how long they have a particular value, allowing you to understand how long an item was In progress before moving to Done status.

Below is an example of the webhook which includes the previous and current value for single select, text, number, iteration, and date project custom fields using the changes parameter.

"changes": {
    "field_value": {
        "field_node_id": "PVTSSF_lADOBH2n9s4Aje1Izgb1kEs",
        "field_type": "single_select",
        "field_name": "Status",
        "project_number": 18,
        "from": {
            "id": "f75ad846",
            "name": "Todo",
            "color": "GREEN",
            "description": "This item hasn't been started"
        },
        "to": {
            "id": "47fc9ee4",
            "name": "In Progress",
            "color": "YELLOW",
            "description": "This is actively being worked on"
        }
    }
},

✨ Bug fixes and improvements

• Added the convertProjectV2DraftIssueItemToIssue GraphQL mutation to convert drafts to issues
• Fixed an error message when resizing columns in the table layout
• Fixed errors when migrating a classic project to the new Projects experience
• Fixed a bug where updating an issue in the project side panel didn't reflect in the project view
• Fixed the rendering of special characters in a single-select field description from the table layout cell dropdown
• Fixed a bug where a space could not be added in project chart titles

✍️ Tell us what you think!

Share your feedback by posting a comment below 👇 How are you going to use this in your projects?

See how to use GitHub for project planning with GitHub Issues, check out what's on the roadmap, and learn more in the documentation.

[zsloane]

Is this available in Actions or only for webhooks to external services?

[rileybroughten]

This is only available for webhooks to external services, as action workflows are currently only triggered by events in your repository, rather than projects that live at the organization level.