Ephemeral Review Apps with Vercel and GitLab

In an earlier article, I covered provisioning the infrastructure for this web site. Here, I want to outline the process of creating ephemeral preview deployments using Vercel and GitLab environments. It assumes that Vercel has already been configured.

My goal when a merge request is opened on the webapp repo’s default branch was to:

• Spin up a live preview deployment in Vercel containing the proposed changes.
• Present the generated preview deployment URL in the Merge Request, so changes can be reviewed interactively.
• Run E2E tests on the preview deployment to validate functionality.
• Teardown the preview deployment once the merge request is completed.
• Merge the approved changes into the project’s default branch, then deploy to production.

Spinning Up a Preview Environment

deploy_preview:
    stage: deploy
    dependencies: [build_preview]
    variables:
        VERCEL_ENVIRONMENT: "preview"
        DEPLOYMENT_URL: ""
    environment:
        name: preview/${CI_COMMIT_REF_SLUG}-${CI_COMMIT_SHORT_SHA}
        url: $DEPLOYMENT_URL
        on_stop: teardown_preview
    rules:
        - if: $CI_MERGE_REQUEST_ID
    artifacts:
        paths:
            - $DEPLOYMENT_ENV
        reports:
            dotenv: $DEPLOYMENT_ENV
    before_script:
        - npm i -g vercel
        - vercel pull --yes --environment=$VERCEL_ENVIRONMENT --token $VERCEL_API_TOKEN
    script:
        - export DEPLOYMENT_URL=$(vercel deploy --prebuilt --token ${VERCEL_API_TOKEN})
        - echo "DEPLOYMENT_URL=${DEPLOYMENT_URL}" > $DEPLOYMENT_ENV

The vercel deploy --prebuilt command deploys the build artifacts created by build_preview to a preview environment in Vercel, and returns a dynamic URL. The URL is scraped from stdout and passed to the GitLab environment as $DEPLOYMENT_URL. The URL is then linked in the merge request.

The URL is also passed as an artifact to the subsequent teardown_preview job.

Tearing Down a Preview Environment

Once the merge request has been closed, the preview environment is no longer needed.

teardown_preview:
    stage: teardown
    dependencies: [deploy_preview]
    environment:
        name: preview/${CI_COMMIT_REF_SLUG}-${CI_COMMIT_SHORT_SHA}
        action: stop
    rules:
        # Should match deploy_preview rule, but be manually triggered
        - if: $CI_MERGE_REQUEST_ID
          when: manual
    before_script:
        - npm i -g vercel
    script:
        - source $DEPLOYMENT_ENV # Load URL from artifact
        - vercel remove --yes $DEPLOYMENT_URL --token $VERCEL_API_TOKEN --scope $VERCEL_TEAM_SLUG

The teardown_preview job is triggered from within the merge request or when the GitLab preview environment is stopped. The vercel remove command instructs Vercel to delete a deployment matching the $DEPLOYMENT_URL argument. For deployments to a Vercel team, the team slug must also be provided via the --scope switch. Once the environment has been deleted in Vercel, it is then removed from GitLab, and cleanup is completed.