tutorial

How to integrate Qovery with GitHub Actions

Learn how to integrate Qovery with GitHub Actions
type: tutorialtechnology: github

Getting started with Qovery is easy. Just plug your Git repository, and you can deploy your application directly. But in some cases you will want a more advanced CI workflow where some steps need to happen before deployment.

One of the CI tools you can use for that matter is GitHub Actions.

If you don't have an application running on Qovery yet, check the documentation to create one.

Goal

In this tutorial, we will deploy an application with GitHub Actions by using the Qovery CLI.

Get your application ready

The first thing we need to do, is to disable automatic deployments. By default, Qovery applications get re-deployed whenever you push some code to the configured branch. Since we want to trigger the deployment through GitHub Actions, we need to disable this behavior.

Go to your application page, then click Settings:

Then on the General section go to the Auto-deploy field, select Off:

Click save.

Add your GitHub Actions Workflow

We will now add a GitHub Actions workflow to your application. Workflow are defined with YAML configuration files that are placed in the code directory of your application. As an example we will define a workflow for a NodeJS application. We will first run our unit tests, then launch the Qovery deployment if the tests pass.

You can adapt those steps for your own stack and needs. Read the GitHub Actions documentation to learn more.

  1. Create the Workflows directory

    All your workflows files must be stored in a specific .github/workflows directory. Create this directory at the root of your project.

  2. Add a Test and Deploy workflow

    In your Workflows folder, create a test-and-deploy.yaml file with the following content:

    .github/workflows/test-and-deploy.yaml
    name: Test And Deploy to Qovery
    on:
      workflow_call:
        secrets:
          api-token:
            required: true
    jobs:
      test:
        runs-on: ubuntu-latest
        steps:
        - uses: actions/checkout@v2
        - name: Install modules
          run: yarn
        - name: Run tests
          run: yarn test
      deploy:
        needs: test
        runs-on: ubuntu-latest
        name: Deploy on Qovery
        steps:
          - name: Deploy with Qovery
            uses: actions/checkout@v3
            env:
              QOVERY_CLI_ACCESS_TOKEN: ${{ secrets.QOVERY_CLI_ACCESS_TOKEN }}
            shell: bash
            run: |
              # Download and install Qovery CLI
              curl -s https://get.qovery.com | bash
    

              qovery application deploy \
                --organization <your_org_name> \
                --project <your_project_name> \
                --environment <your_environment_name> \
                --application <your_qovery_app_name> \
                --commit-id ${{ github.sha }} \
                --watch
    • The on section contains a workflow_call directive. It means that this workflow will be triggered when called from another workflow. We're doing this because we won't use this workflow directly. Since we might have several environments to deploy to Qovery depending on the branch, we could have one workflow per environment, and we want to avoid repeating all the steps.
    • The inputs and secrets sections are defining the values that we will need to pass to our workflow
    • The jobs section lists the jobs and the steps that in needs to accomplish. Here we have two jobs and five steps:
      • test where we check out the code, we install Yarn modules, and we run tests through Jest
      • deploy where we check out the code and deploy to Qovery.

    Several things worth noting:

    • The organization / project / environment / application are case-sensitive.
    • Our deploy job has a needs instructions, telling GitHub Actions that this job can only run when the test job succeeds.
    • The with section of our last deploy step contains interpolated strings: ${{ inputs.xxxx }}. Those are values passed to our workflow, that our Qovery action needs. They will be passed from the calling workflow.

  3. Get a Qovery API token

    To get an API token, use the Qovery CLI:

    qovery token
    • Select your organization. (tokens are valid for only one organization).
    • Enter a name for your token.
    • Enter a description for your token.

    You will get an output like this one:

    qovery token Qovery: ---- Never share this authentication token and keep it secure ----
    Qovery: qov_xxx....
    Qovery: ---- Never share this authentication token and keep it secure ----

  4. Add your token to your GitHub repository secrets

    Go to your GitHub repository then to the Settings:

    Got to the Secrets/Actions section and click on New repository secret:

    Add your secret with the name QOVERY_API_TOKEN and save:

Execute the GitHub Actions Pipeline

We're done with the setup. You can now push your code to the main branch. If you did it properly, under the Actions tab on your GitHub repository, you should see your job being run.

You can click on it to see the details of the jobs. Once the testing phase is green, it will start the deployment job.

As soon as the job is set up, and it starts actually deploying, go to the Qovery console and check that your application is actually being deployed.

Advanced use-cases

It's possible to support any use cases by using the Qovery CLI. Like cloning an environment, changing the branch of some applications and deploying only a subset of applications. Refers to the Qovery CLI documentation to explore all the commands that you can use.

Check out our GitHub Actions integration page to check out more examples.

Conclusion

Integrating Qovery with GitHub Actions enables more complex workflows than just deploying on code push. You can make sure your test suite succeeds before deploying or anything else you need, without sacrificing the simplicity of deployment Qovery brings you.