Frontend Release Strategy Process

This document outlines the CRUK frontend release process for products.

tip

For additional context on this best practice see Environments.

Description

The methods and processes used to release code to production in CRUK can be referenced from the Release Process document. In this document we will focus on the frontend release process.

Types of Deployments

Vercel

Vercel is a platform for deploying static sites and serverless functions. It is used to deploy the frontend of the CRUK Events Management registration platform. The frontend is built using Next.js and is deployed to Vercel using the Vercel API through GitHub Actions.

As referenced in the Release Process document, the process of deploying to production is preceded through a series of local development, pull requests and a thorough review process before deployment to pre-production and then subsequently to production. The standard process for Vercel is as follows:

1. A change is made to the codebase on a branch in GitHub.
2. A pull request is created against the main branch.
3. Unit and integration tests are run against the pull request.
4. If the PR involves frontend changes, the feature branch owner has the option to initiate a deployment to a ephemeral PR environment. This is a short lived environment that is spun up per PR and asserts that the software can be build and deployed. This allows other reviewers, especially QA, the ability to review the changes through the UI.
5. Once code, automated and manual checks have passed, the PR is approved and merged into the main branch which then triggers a deployment to the integration environment.

PR deployments follow the same process as prod deployments where a Vercel token is used to interact with the Vercel API and execute the deploy command. In order for this to take place the feature branch owner must have the Vercel token stored in a GitHub secret as well as the organisation and project ID for the targeted Vercel project.

The use of GitHub Actions allows developers the chance to customise the deployment process where dynamic values can be passed to the deployment commands to differentiate between environments. This is very useful when it comes to applying custom domain names to the deployed environments. The alias command is used to help sustain a consistent domain for our integration environment to ensure other services that rely on the domain name are not affected anytime there is an update to integration:

- name: Set vercel integration url
  if: inputs.environment == 'int'
  run: |
    vercel alias rm --yes eventsreg.int.events.app.crnet.org --token=${{ secrets.VERCEL_TOKEN }} --scope=cruk || true
    vercel alias set $(cat deployment-url.txt) eventsreg.int.events.app.crnet.org --token=${{ secrets.VERCEL_TOKEN }} --scope=cruk

For production deployments, we can now take the latest deployment (integration) and promote it to our production environment. This is done by using the vercel promote command:

- name: Promote production deployment
  if: inputs.environment == 'prod'
  run: vercel promote $(cat deployment-url.txt) --token=${{ secrets.VERCEL_TOKEN }} --scope=cruk

Once deployed to production, automated smoke tests should be run to ensure that the deployment is working as expected:

steps:
  - name: dispatch smoke tests workflow
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    run: |
      gh workflow run smoke-test.yml \
        --repo ${{ github.repository }} \
        --field ref=${{ github.event.inputs.ref }}

Amplify

Amplify is a platform for deploying static sites and serverless functions. You can find it for example being used to deploy the frontend of the CRUK Online Payments platform. There are mutiple ways to deploy to Amplify, the most common is through the Amplify CLI that can be utilised as part of a wider CI/CD pipeline process.

The process of having emphemeral environments for PRs, the promotion of latest code changes to production and post release automated smoke tests is very similar to the process for Vercel. However, there are some differences in the way that Amplify is configured and deployed.

A typical setup for Amplify deployments is as follows:

1. Configure Amplify:

• Create an Amplify app in the AWS Console.
• Connect it to your GitHub repository.
• Set up environment variables if needed.

2. Configure the build settings:

• Can be done in the Amplify Console or more commonly by using a build specification (amplify.yml) file to define the build process.

An example of a build specification file from Online Payments is as follows:

version: 1
applications:
  - appRoot: frontend
    frontend:
      artifacts:
        baseDirectory: out
        files:
          - '**/*'
      cache:
        paths:
          - node_modules/**/*
      phases:
        preBuild:
          commands:
            - npm install
        build:
          commands:
            - npm run build

3. Configure the deployment settings on CI/CD:

• Create a GitHub Actions workflow that triggers an Amplify deployment (a full example can be found here):

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
    ...

jobs:
  set-config:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    outputs:
      awsAccount: ${{ steps[inputs.environment].outputs.awsAccount }}
      awsRole: ${{ steps[inputs.environment].outputs.awsRole }}
      appId: ${{ steps[inputs.environment].outputs.appId }}
    steps:
      ...

  frontend-infrastructure:
    ...

  frontend-deployment:
    runs-on: ubuntu-latest
    needs: [set-config, frontend-infrastructure]
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: CRUKorg/cruk-configure-aws-credentials@v4
        with:
          aws-role-arn: arn:aws:iam::${{ needs.set-config.outputs.awsAccount }}:role/${{ needs.set-config.outputs.awsRole }}
          aws-region: "eu-west-2"

      - name: Start Frontend AWS Amplify job
        run: aws amplify start-job --app-id ${{ needs.set-config.outputs.appId }} --branch-name main --job-type RELEASE --job-reason ${{ github.ref }}

Just like Vercel, domain aliases are also possible in Amplify, with the ability to create custom domain names for different branches of an application. Branches can be mapped to specific subdomains of a custom domain setup in the used AWS account. This is set up in the Amplify Console under "Domain management.". When a branch is deployed, its URL alias updates, making it more manageable to manage multiple environments under one domain.

Further information on how a setup such as this is currently utilised can be found in the Fundraising Web App Amplify Deployment Docs.

Currently, efforts are being made to move towards GitHub Actions for CI/CD for any teams that are currently using legacy AWS CodePipeline oriented deployments.

Advice

In regards to best practices for frontend deployments, a lot of relevant information can be found in the Release Process document.

Rationale

Having multiple options for deploying frontend packages to production allows developers to choose the best option for their product and innovate with the latest technologies and best practices. This allows teams to focus on developing features whilst ensuring that there is strong consistency between local, integration and production environments.

Examples

The Online Payments frontend can be used as an example for a product that encapsulates the Amplify release process.

The Events Management frontend can be used as an example for a product that encapsulates the Vercel release process.

References & Further Reading

• AWS Amplify
• Vercel
• Github releases
• Fundraising Web App Amplify Deployment Docs