Skip to main content

Continuous Integration / Delivery (CI/CD)

This guide explains the necessary steps for continuous integration on your viktor application and provides some example files for frequently used CI-platforms. See this article for an introduction on the concepts of continuous integration if you're unfamiliar with the topic.

Setting up the environment

First you need to make sure that your CI environment is the same as the environment in which your app will run. This means:

  • Linux machine
  • Matching Python version
  • Environment variables VIKTOR_DEV and VIKTOR_TOKEN should be set. You don't have to use your own developer credentials. Contact VIKTOR for extra CI credentials.
  • Environment variable VIKTOR_ENV should be set with the environment you are publishing to (e.g. {company}.viktor.ai).

Implementation of tests

  1. Download the CLI. This is the entry point which is used to obtain the SDK:

    curl -Lo viktor-cli 'https://developers.viktor.ai/api/v1/get-cli/?platform=linux&format=binary' && chmod +x viktor-cli
  2. Install the app and its dependencies (SDK, connector, other packages):

    • Make sure you only use ci-install in the ci job and install during local development.
    • The ci-install command is an alias for a very involved pip install command, which would otherwise pollute your local Python environment.
    • The install command does not work in your ci environment
    ./viktor-cli ci-install
  3. Perform all tests (found in the 'tests' directory)

    ./viktor-cli ci-test

Publishing apps

note

Currently the following CI-platforms are supported:

  • Azure Pipelines
  • Github Actions
  • Gitlab CI/CD

The CLI can be used to automate the publishing of apps in CI pipelines with the ci-publish command. We recommended creating a Git tag to reference specific versions of the app code you are publishing on the platform. It is possible to conditionally trigger pipelines / workflows only when a tag is created.

./viktor-cli ci-publish <NAME>

The CLI determines which CI-platform is used based on platform-specific environment variables. Subsequently, all information required to publish your app is collected by the CLI and used to create a publication context. This context is stored together with the app version for later reference. The variables used to determine the publication context are shown in the table below.

Azure PipelinesGithub ActionsGitlab CI/CD
User nameBuild.RequestedForGITHUB_ACTORGITLAB_USER_NAME
User emailBuild.RequestedForEmailn.a.GITLAB_USER_EMAIL
Commit hashBuild.SourceVersionGITHUB_SHACI_COMMIT_SHA
Branch or tag refBuild.SourceBranchNameGITHUB_REF_NAMECI_COMMIT_REF_NAME
Pipeline URLSystem.TeamFoundationCollectionUri, System.TeamProject, Build.BuildId1GITHUB_SERVER_URL, GITHUB_REPOSITORY, GITHUB_RUN_ID1CI_PIPELINE_URL
TagBuild.SourceBranchNameGITHUB_REF_NAMECI_COMMIT_TAG

Example CI files

Below are examples of configuration files for frequently used CI platforms. In the examples below you should replace NAME with the name of the app as it is registered on the platform.

Azure Pipelines

variables:
- group: VIKTOR # variable group within DevOps library containing the variables VIKTOR_DEV and VIKTOR_TOKEN
jobs:
- job: test
container: python:3.7-buster
steps:
- bash: curl -Lo viktor-cli 'https://developers.viktor.ai/api/v1/get-cli/?platform=linux&format=binary' && chmod +x viktor-cli
- bash: ./viktor-cli ci-install
- bash: ./viktor-cli ci-test
- job: publish
container: python:3.7-buster
condition: and(succeeded(), startsWith(variables['Build.SourceBranch'], 'refs/tags/')) # only run for a tag and when previous job completed successfully
steps:
- bash: curl -Lo viktor-cli 'https://developers.viktor.ai/api/v1/get-cli/?platform=linux&format=binary' && chmod +x viktor-cli
- bash: ./viktor-cli ci-publish NAME # replace NAME with the actual name of the app

Github Actions

name: viktor-test-publish
on: push
env:
VIKTOR_DEV: ${{ secrets.VIKTOR_DEV }}
VIKTOR_TOKEN: ${{ secrets.VIKTOR_TOKEN }}
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v3
with:
python-version: '3.7'
- run: curl -Lo viktor-cli 'https://developers.viktor.ai/api/v1/get-cli/?platform=linux&format=binary' && chmod +x viktor-cli
- run: ./viktor-cli ci-install
- run: ./viktor-cli ci-test
publish:
runs-on: ubuntu-latest
needs: test # start when job 'test' is finished
if: ${{ success() && startsWith(github.ref, 'refs/tags/') }} # only run for a tag and when previous job completed successfully
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v3
with:
python-version: '3.7'
- run: curl -Lo viktor-cli 'https://developers.viktor.ai/api/v1/get-cli/?platform=linux&format=binary' && chmod +x viktor-cli
- run: ./viktor-cli ci-publish NAME # replace NAME with the actual name of the app

Gitlab CI/CD

stages:
- test
- publish

image: python:3.7-buster

test:
stage: test
script:
# download CLI
- curl -Lo viktor-cli 'https://developers.viktor.ai/api/v1/get-cli/?platform=linux&format=binary' && chmod +x viktor-cli

# install app and dependencies
- ./viktor-cli ci-install

# perform tests
- ./viktor-cli ci-test

publish:
stage: publish
script:
# download CLI
- curl -Lo viktor-cli 'https://developers.viktor.ai/api/v1/get-cli/?platform=linux&format=binary' && chmod +x viktor-cli

# publish the app
- ./viktor-cli ci-publish NAME # replace NAME with the actual name of the app
only:
- tags
when: manual

CircleCI

caution

Publishing of viktor apps using ci-publish is currently not supported for CircleCI

version: 2
jobs:
test:
docker:
- image: python:3.7-buster
steps:
- checkout

# download CLI
- run: curl -Lo viktor-cli 'https://developers.viktor.ai/api/v1/get-cli/?platform=linux&format=binary' && chmod +x viktor-cli

# install app and dependencies
- run: ./viktor-cli ci-install

# perform tests
- run: ./viktor-cli ci-test

TravisCI

caution

Publishing of viktor apps using ci-publish is currently not supported for TravisCI

language: python
python:
- "3.7"

script:
# download CLI
- curl -Lo viktor-cli 'https://developers.viktor.ai/api/v1/get-cli/?platform=linux&format=binary' && chmod +x viktor-cli

# install app and dependencies
- ./viktor-cli ci-install

# perform tests
- ./viktor-cli ci-test

  1. These variables are combined into a URL to the pipeline / workflow that triggered the ci-publish command.