Quant static site construction banner

 

In a recent post, I introduced the Quant CLI tool and covered an example of how your might set up a CircleCI pipeline to deploy your static site build to Quant. As part of the series, I want to explore other cloud-based CI providers, and today I'm going to look at Github Actions. I've set up an example repository for this article that deploys a Gatsby application via actions, so you can follow the code over at the example repo.

GitHub Actions is a relatively new CI product offered by GitHub for hosted repositories. There is a large ecosystem of community provided actions to help automate many deployment workflows, from deploying to Azure, AWS or Heroku to updating JIRA tickets. There are many actions to add to your pipelines to complete your workflows, so it makes sense that we look to provide an action to make deploying to Quant as easy as possible.

Secure your access token

Before we begin with the action, we should make sure we store the quant token in a secure location that makes it accessible to our workflows, but not accessible to contributors. You will need administrative access to the repository to add secrets, under the settings page for your repository you will see secrets. This allows you to add your Quant API token and have it available to your deploy workflow. By default, the token will not be shared with forks of your repository - which makes this the recommended way to store your token and automate the deployment.

In the provided examples, when you see secrets.QUANT_TOKEN, this is the variable name we have given the deploy key, so just replace QUANT_TOKEN with the name you give the the variable and it should be interchangeable.

Another thing to note with secrets, in my testing so far, anything accessed with secrets. is obfuscated in the actions output, for example using the action you will see:

-v "/home/runner/work/deploy-action/deploy-action":"/github/workspace" quantcdn/cli:latest "deploy" 
"/github/workspace/build" "-c quant" "-t ***" "-p github-actions"

You can read more about GitHub Actions and secrets on GitHub's docs pages, very helpful stuff!

Using the community Action

An action will let you control the entire workflow and will let the Quant repository manage how Quant is installed and run. This leaves application building up to you and deployments up to Quant. The deployment step will look like:

- name: 'Deploy to Quant'
  uses: quantcdn/deploy-action@v1.0.0
  with:
    customer: your-customer-id
    project: your-project-id
    token: ${{ secrets.QUANT_TOKEN }}
    dir: build

That's it! With that added, the Quant action will be able to pick up your build artifact and will be able to deploy your assets to Quant.

That made for a pretty short post :) so let's break down the action parameters and make sure we're all on the same page. All the Quant parameters can be found on the projects dashboard in the integrations section.

  • customer: This is the Quant customer (not your user account) the organization that the project belongs to
  • project: This is the machine name of the project that you want to deploy
  • token: This should be added as a repository secret and referenced here
  • dir: The build directory for your application - the Quant CLI tool will deploy all files that it finds in the specified directory

GitHub Actions can help deploy your project to Quant with ease. If GitHub Actions aren't available to your workflow, read on for some alternative ways to interface directly with the CLI tool.

Optional: Cache the last deployment status for faster deployments

The deployment action supports outputting a revision log, which tracks the md5 hash of all the built artefacts that end up being deployed to Quant. If an existing revision log is found, then the deployment process will skip any assets that already have a matching md5 for content published in the Quant edge.

This can speed up deployment times considerably, especially if your built output contains large assets.

To enable this feature, first add the "revision-log" option to your deploy-action stage, and ensure the file is cached in actions as follows:

- name: Cache local revision file
  id: cache-quant-revisions
  uses: actions/cache@v2
  with:
    path: .quant-revision
    key: quant-revision

- name: 'Deploy to Quant'
  uses: quantcdn/deploy-action@v1.0.0
  with:
    customer: your-customer-id
    project: your-project-id
    token: ${{ secrets.QUANT_TOKEN }}
    dir: build
    revision-log: .quant-revision

That's all there is to it! When you run the build pipeline again you will see the deployment will only deploy the delta between the previous build, leading to much faster deploy times!

Alternatives

The Quant CLI tool is provided in two formats, a docker image and an npm package. Both of these options provide flexibility with how you define your workflows and, while we provide a standard action, there a number of reasons that this option might be not available to your workflow. Let's go through the other options to give you full control over the deployment process.

Adding Quant as a dependency

The Quant CLI tool can be added as a dependency with npm. This will install the tool locally and make the packaged script available to you, so you can create npm scripts to execute operations.

First, you'll need to add the dependency; this can be either type of dependency as long as it's installed in the action.

npm i @quantcdn/quant-cli -D

You would then create an npm script to handle the deployment. Add the following to your package.json

"quant": "quant"

You can then use npm run quant with the necessary parameters and options to deploy your application which might look like:

jobs:
  deploy:
    runs-on: node
    steps:
      # Checkout, build and test your application in stages prior.
      - name: Deploy
        env:
          CUSTOMER: my-quant-customer-id
          PROJECT: my-quant-project-id
          TOKEN: ${{ secrets.QUANT_TOKEN }}
        run: npm run quant deploy $PWD/build -c $CUSTOMER -p $PROJECT -t $TOKEN

Using the Quant CLI container

The Quant CLI container is available from Docker Hub and is based on node:14, as a result it makes a decent runtime to build Node applications. You can use this container to perform your whole workflow similarly to using the node container directly and at the end run quant deploy. For example:

jobs:
  deploy:
    runs-on: ubuntu-latest
    container:
      image: quantcdn/cli:latest
    steps:
      # Checkout, build and test your application in stages prior.
      - name: Deploy
        env:
          CUSTOMER: my-quant-customer-id
          PROJECT: my-quant-project-id
          TOKEN: ${{ secrets.QUANT_TOKEN }}
        run: quant deploy $PWD/build -c $CUSTOMER -p $PROJECT -t $TOKEN

Getting creative with uses

The Github syntax is pretty accommodating. There are ways that you can run the image directly via the docker daemon in a step. This is a little undocumented and implementation may change as the product evolves, so I would definitely recommend using one of the above methods - but if you're looking for a quick way to get in and test the workflow you can do something like:

steps:
  - name: Deploy
    uses: docker://quantcdn/cli:latest
    with:
      entrypoint: quant
      args: deploy /github/workspace/build -c my-quant-customer-id -p my-quant-project-id -t $({ secrets.QUANT_TOKEN })

When the runner executes the step it constructs a docker command that looks like:

/usr/bin/docker run --name quantcdnclilatest_2dcc06 --label 5588e4 --workdir /github/workspace --rm 
-e INPUT_ENTRYPOINT -e INPUT_ARGS -e HOME -e GITHUB_JOB -e GITHUB_REF -e GITHUB_SHA 
-e GITHUB_REPOSITORY -e GITHUB_REPOSITORY_OWNER -e GITHUB_RUN_ID -e GITHUB_RUN_NUMBER -e GITHUB_RETENTION_DAYS 
-e GITHUB_ACTOR -e GITHUB_WORKFLOW -e GITHUB_HEAD_REF -e GITHUB_BASE_REF -e GITHUB_EVENT_NAME -e GITHUB_SERVER_URL 
-e GITHUB_API_URL -e GITHUB_GRAPHQL_URL -e GITHUB_WORKSPACE -e GITHUB_ACTION -e GITHUB_EVENT_PATH 
-e GITHUB_ACTION_REPOSITORY -e GITHUB_ACTION_REF -e GITHUB_PATH -e GITHUB_ENV -e RUNNER_OS -e RUNNER_TOOL_CACHE 
-e RUNNER_TEMP -e RUNNER_WORKSPACE -e ACTIONS_RUNTIME_URL -e ACTIONS_RUNTIME_TOKEN -e ACTIONS_CACHE_URL 
-e GITHUB_ACTIONS=true -e CI=true --entrypoint "quant" --network github_network_29b07e0cd5ac4c33b0a7b58f9c6b368e 
-v "/var/run/docker.sock":"/var/run/docker.sock" -v "/home/runner/work/_temp/_github_home":"/github/home" 
-v "/home/runner/work/_temp/_github_workflow":"/github/workflow" -v "/home/runner/work/_temp/_runner_file_commands":"/github/file_commands"
-v "/home/runner/work/gatsby-actions-example/gatsby-actions-example":"/github/workspace" quantcdn/cli:latest {args}

Hopefully this has helped you consider how you can automate your deployments to Quant and provides another example of how you can do that. Stay tuned for the next post in the series!