GitHub - vercel/repository-dispatch: Utilities for working with dispatch events triggered by Vercel

Utilities and types for working with repository_dispatch events triggered by Vercel.

Examples

Using in CI

The ci-example shows common ways to use repository_dispatch events in a CI workflow for GitHub projects connected to Vercel.

Events

Supported Events

on:
  repository_dispatch:
    types:
      # Deployment has been promoted to production (automatic or manual)
      - 'vercel.deployment.promoted'
      # Deployment has finished building and has automatically been promoted to production
      - 'vercel.deployment.success'
      # Deployment has finished building, but has not been promoted to production
      - 'vercel.deployment.ready'
      # Deployment has failed to build
      - 'vercel.deployment.error'
      # Deployment has been canceled
      - 'vercel.deployment.canceled'
      # Deployment canceled as a result of the ignored build script (https://vercel.com/docs/project-configuration/git-settings#ignored-build-step)
      - 'vercel.deployment.ignored'
      # Deployment canceled as a result of automatic deployment skipping (https://vercel.com/docs/monorepos#skipping-unaffected-projects)
      - 'vercel.deployment.skipped'
      # Deployment waiting to start building pending
      - 'vercel.deployment.pending'
      # Deployment has failed
      - 'vercel.deployment.failed'

NOTE: Wildcards are supported for the type field:

on:
  repository_dispatch:
    types:
      # All deployment events
      - 'vercel.deployment.*'

Payload Example

{
  "environment": "production",
  "git": {
    "ref": "main",
    "sha": "abcdef1234567890abcdef1234567890abcdef12",
    "shortSha": "abcdef1"
  },
  "id": "dpl_1234567890abcdefghijklmnopqrstuvwxyz",
  "project": {
    "id": "prj_abcdef1234567890abcdef1234567890",
    "name": "example-project"
  },
  "state": {
    "type": "pending"
  },
  "url": "https://example-project-abc123.vercel.app"
}

Note

View the complete Typescript definitions for this payload here.

Actions

Checkout - Automatically checks out the ref from the SHA of the deployment.

Important

This should be used whenever your action needs to

Checkout your repository
The checkout should run in the context of the repository when the deployment was created.

This is required because GitHub repository_dispatch events are always triggered using the last commit on default branch as the GITHUB_SHA in the context of the workflow.

Status - Automatically sets a commit status for the ref associated with the deployment.

Important

This should be used whenever your action needs to

Checkout your repository
The checkout should run in the context of the repository when the deployment was created.

This is required because GitHub repository_dispatch events are always triggered using the last commit on default branch as the GITHUB_SHA in the context of the workflow.

Debug - Echos the repository dispatch event payload for debugging purposes.