Image
Steve
Steve Worley

Deploying to Quant with Github Actions

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, 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 availble to your deploy workflow, by default the token will not be shared with forks of your repository - which makes this the recommend way to store your token and automate the deploy.

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 Actions and secrets on Githubs 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 artefact and will be able to deploy your assets to Quant, that'd make for a pretty short post - so lets break down the action parameters and make sure that we're all on the same page. All the quant parameters can be found on the projects dashboard.

  • customer: This is the quant customer (not your user account) the organisation 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.

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 will 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 its 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!