Deployment integration actions

With deployment integration actions, integration providers can enable integration resource tasks to be performed such as branching a database, setting environment variables, and running readiness checks. It then allows integration users to configure and trigger these actions automatically during a deployment.

For example, you can use deployment integration actions with the checks API to create integrations that provide testing functionality to deployments.

1. Action declaration:

   • An integration product declares deployment actions with an ID, name, and metadata.
   • Actions can specify configuration options that integration users can modify.
   • Actions can include suggestions for default actions to run such as "this action should be run on previews".

2. Project configuration:

   • When a resource is connected to a project, integration users select which actions should be triggered during deployments.
   • Integration users are also presented with suggestions on what actions to run if these were configured in the action declaration.

3. Deployment execution:

   • When a deployment is created, the configured actions are registered on the deployment.
   • The registered actions trigger the deployment.integration.action.start webhook.
   • If a deployment is canceled, the deployment.integration.action.cancel webhook is triggered.

4. Resource-side processing:

   • The integration provider processes the webhook, executing the necessary resource-side actions such as creating a database branch.
   • During the processing of these actions, the build is blocked and the deployment set in a provisioning state.
   • Once complete, the integration provider updates the action status.

5. Deployment unblock:

   • Vercel validates the completed action, updates environment variables, and unblocks the deployment.

As an integration provider, to allow your integration users to add deployment actions to an installed native integration, follow these steps:

1. Declare deployment actions

   Declare the deployment actions for your native integration product.

   1. Open the Integration Console.
   2. Select your Marketplace integration and click Manage.
   3. Edit an existing product or create a new one.
   4. Go to Deployment Actions in the left-side menu.
   5. Create an action by assigning it a slug and a name.

   Next, handle webhook events and perform API actions in your integration server. Review the example marketplace integration server code repository.

2. Handle the deployment start

   Handle the deployment.integration.action.start webhook. This webhook triggers when a deployment starts an action.

   This is a webhook payload example:

   {
     "installationId": "icfg_1234567",
     "action": "branch",
     "resourceId": "abc-def-1334",
     "deployment": { "id": "dpl_568301234" }
   }

   This payload provides IDs for the installation, action, resource, and deployment.

3. Use the Get Deployment API

   You can retrieve additional deployment details using the Get a deployment by ID or URL endpoint:

   curl https://api.vercel.com/v13/deployments/dpl_568301234 \
     -H "Authorization: {access_token}"

   You can create your access_token from Vercel's account settings.

   Review the full code for handling the deployment start in the example marketplace integration server.

4. Complete a deployment action

   Once an action is processed, update its status using the Update Deployment Integration Action REST API endpoint.

   Example request to this endpoint:

   PATCH https://api.vercel.com/v1/deployments/{deploymentId}/integrations/{installationId}/resources/{resourceId}/actions/{action}

   Example request body to send that includes the resulting updated resource secrets:

   {
     "status": "succeeded",
     "outcomes": [
       {
         "kind": "resource-secrets",
         "secrets": [{ "name": "TOP_SECRET", "value": "****" }]
       }
     ]
   }

5. Handle deployment cancellation

   When a deployment is canceled, the deployment.integration.action.cancel webhook is triggered. You should handle this action to clean up any partially completed actions.

   Use the deployment.integration.action.cleanup webhook to clean up any persistent state linked to the deployment. It's triggered when a deployment is removed from the system.