README.md

Vercel Azure DevOps Extension

This extension contains Azure Pipelines tasks for automatically deploying your Azure DevOps project to Vercel.

• Vercel Azure DevOps Extension
  • Extension Set Up
  • Basic Pipeline Set Up
  • Full Featured Pipeline Set Up
  • Extension Reference
    • Task: vercel-deployment-task
    • Task: vercel-azdo-pr-comment-task
  • Azure PAT Set Up
  • Azure Build Policy Set Up

Extension Set Up

1. Create a Vercel Project
2. Create a Vercel Personal Access Token with permissions to deploy the project created on step 1 (see the Vercel PAT Set Up guide for more information)
3. If you're planning on using the Pull Request Commenting Task, create an Azure DevOps Personal Access Token with permissions to Read/Write Pull Request threads (see the Azure PAT set up guide for more information)
4. Store the tokens as secret variables in your preferred methodology. Azure recommends using the UI, Variables Groups, or Azure Key Vault. Whichever methodology you use, make sure it is accessible from Azure Pipelines.
5. Navigate to the Vercel Deployment Extension Visual Studio Marketplace page and add the extension to your organization.

   Note: This step will not work until the extension is shared with the user or we make the extension public.

6. With the extension added, you are now ready to use the tasks in your Azure Pipeline. The tasks are referable using vercel-deployment-task and vercel-azdo-pr-comment-task.

   Note: Within a pipeline definition, the tasks will be used like - task: vercel-deployment-task@1. The @1 represents the Major version of the task that the pipeline should use. Make sure to indicate the latest major version of the task when creating your pipeline.

Explore the following pipeline guides for further set up instructions:

• Basic Pipeline Set Up
• Full Featured Pipeline Set Up

Basic Pipeline Set Up

This short guide will demonstrate how the extension can be used to automatically deploy the main branch to production. Make sure the steps in Extension Set Up have been completed.

1. Start by creating a new pipeline file in your repo called basic-pipeline.yml. Either use the in-browser editor, or in your local file editor.

2. Add a trigger:, pool:, and steps: declarations:

   trigger:
     - main
   
   pool:
     vmImage: ubuntu-latest
   
   steps:
   # - task: ...

   The trigger: declaration states that this pipeline should run for all commits to the main branch.

3. Now add the extension's task vercel-deployment-task:

   steps:
     - task: vercel-deployment-task@1
       name: Deploy
       inputs:
         vercelProjectId: "<project-id>"
         vercelOrgId: "<team-id>"
         vercelToken: "<vercel-token>" # '$(VERCEL_TOKEN)'
         production: true

   • The vercelToken should reference the secret variable defined in Extension Set Up.

4. Commit, and push the pipeline to the repository.

5. Navigate to Azure Pipelines and run the task for the first time if it doesn't run automatically.

6. Make a change to your project and commit to the main branch, a new deployment pipeline run should automatically kick off in Azure Pipelines, and the Vercel Project should automatically update.

Full Featured Pipeline Set Up

This guide will demonstrate how to improve the Basic Pipeline Set Up pipeline in order to deploy from main to production and deploy from pull requests to preview.

1. Starting with the pipeline file created in Basic Pipeline Set Up, duplicate, rename, or open it in your editor of choice.
2. Add a variable above the steps block

   variables:
     isMain: $[eq(variables['Build.SourceBranch'], 'refs/heads/main')]

3. Update the production: true input to be production: $(isMain)
4. Below inputs:, add a condition:

   inputs:
     # ...
   condition: or(eq(variables.isMain, true), eq(variables['Build.Reason'], 'PullRequest'))

5. Then add a new task step immediately after the vercel-deployment-task step, adding the PR commenting feature:

   - task: vercel-azdo-pr-comment-task@1
     inputs:
       azureToken: $(AZURE_PAT)
       deploymentTaskMessage: $(Deploy.deploymentTaskMessage)

   • The vercel-deployment-task sets an output variable called deploymentTaskMessage. The reference $(Deploy.deploymentTaskMessage) comes from the name: Deploy on the vercel-deployment-task step.
6. Push these changes to the repository, and set a Build Policy for the main branch.
7. Now create a new branch, push a commit, and open a PR against main. A new pipeline execution should trigger and it should create a preview deployment on Vercel as well as comment back on the PR with the preview URL.

Extension Reference

Task: vercel-deployment-task

An Azure Pipelines Task Extension for automatically deploying to Vercel.

The configuration inputs vercelProjectID, vercelOrgID, and vercelToken can all be replaced with environment variables. See their respective property sections for more details.

Properties

• vercelProjectId

  The ID of your Vercel Project.

  Can alternatively be set as the environment variable VERCEL_PROJECT_ID.

  Type: string

  Required: false

• vercelOrgId

  The ID of the Vercel Team your Vercel Project is associated with. Starts with team_.

  Can alternatively be set as the environment variable VERCEL_ORG_ID.

  Type: string

  Required: false

• vercelToken

  A Vercel personal access token with deploy permissions for your Vercel Project. Guide

  Can alternatively be set as the environment variable VERCEL_TOKEN.

  Type: string

  Required: false

  • vercelCwd

  The Current Working Directory option can be used to provide a working directory (that can be different from the current directory) when running Vercel deployment task.

  This option can be a relative or absolute path. Guide

  Can alternatively be set as the environment variable VERCEL_CWD.

  Type: string

  Required: false

• production

  Should the task deploy to production? When omitted, or set to false, the task will create preview deployments.

  Type: boolean

  Default: false

  Required: false

• debug

  Enable --debug output for the internal Vercel CLI operations.

  Type: boolean

  Default: false

  Required: false

• archive

  Enable --archive=tgz flag for the internal Vercel CLI operations.

  Type: boolean

  Default: false

  Required: false

• env

  Adding enviroment variables at runtime utilizing Vercel CLI's --env option.

  Type: string

  Required: false

• buildEnv

  Adding build enviroment variables to the build step utilizing Vercel CLI's --build-env option.

  Type: string

  Required: false

• logs

  Enable --logs flag for the internal Vercel CLI operations.

  Type: boolean

  Default: false

  Required: false

Outputs

• deploymentURL

  The URL of the deployment.

  Type: string

• originalDeploymentURL

  Original URL of the deployment. Can be used to create your own alias in a depending separate task.

  Type: string

• deploymentTaskMessage

  The output from the deployment. Can be passed to Vercel Azure DevOps Pull Request Comment Task.

  Type: string

Task: vercel-azdo-pr-comment-task

Properties

• azureToken

  An Azure personal access token with the Git 'PullRequestContribute' permission for your Azure DevOps Organization. Guide

  Type: string

  Required: true

• deploymentTaskMessage

  The message to be commented on the Pull Request. Generally is created by the Vercel Deployment Task.

  Type: string

  Required: true

Azure PAT Set Up

1. Go to https://dev.azure.com and click on the settings icon in the top right.

2. Click on the Personal access tokens menu option

3. Click on New Token

4. After filling in the basic token information like name, organization, and expiration, click on Custom Defined under Scopes

5. Then, Show all scopes button at the bottom of the prompt

6. Then, within the scopes list, scroll until Pull Request Threads, and select the Read & Write toggle.

7. Click Create, and don't forget to copy the token as once you exit the prompt it will not be retrievable.

Azure Build Policy Set Up

1. Navigate to the Azure DevOps organization Overview page. Click on Project Settings in the lower left corner.

2. In the Project Settings list on the left, scroll down and click on the Repositories option

3. Select the repository

4. On the right side, select Policies

5. Scroll down to Branch Policies, and select the main branch

6. Scroll down to Build Validation, and click on the + button to create a new validation policy.

7. Select the pipeline previously created

Keep the policy marked as Required so that commits directly to main are prevented.

8. Finally, save the new validation policy

9. Create a pull request to the main branch, and if everything is set up correctly, the pipeline will run and comment back on the PR the deployment URL 🎉