Continuous Integration/Deployment

This guide explains the necessary steps for continuous integration on your viktor application and provides some example files for frequently used CI/CD 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. Contact VIKTOR to receive CI-credentials (don't use your personal developer credentials!).
Environment variable VIKTOR_ENV should be set with the environment you are publishing to (e.g. {company}.viktor.ai).

Continuous Integration

Download the CLI, which will be used to perform CI commands:

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

Install the app and its dependencies:
```
./viktor-cli ci-install
```
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
Perform all tests (found in the 'tests' directory):
```
./viktor-cli ci-test
```

Continuous Deployment

note

Currently, publishing is supported for the following CI/CD platforms:

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/CD 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 Pipelines	GitHub Actions	GitLab CI/CD
User name	`Build.RequestedFor`	`GITHUB_ACTOR`	`GITLAB_USER_NAME`
User email	`Build.RequestedForEmail`	n.a.	`GITLAB_USER_EMAIL`
Commit hash	`Build.SourceVersion`	`GITHUB_SHA`	`CI_COMMIT_SHA`
Branch or tag ref	`Build.SourceBranchName`	`GITHUB_REF_NAME`	`CI_COMMIT_REF_NAME`
Pipeline URL	`System.TeamFoundationCollectionUri`, `System.TeamProject`, `Build.BuildId`*	`GITHUB_SERVER_URL`, `GITHUB_REPOSITORY`, `GITHUB_RUN_ID`*	`CI_PIPELINE_URL`
Tag	`Build.SourceBranchName`	`GITHUB_REF_NAME`	`CI_COMMIT_TAG`

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

Example CI/CD files

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

Azure Pipelines
GitHub Actions
GitLab CI/CD
CircleCI
TravisCI

note

Be sure to set the variables VIKTOR_DEV, VIKTOR_TOKEN and VIKTOR_ENV within a variable group with name (e.g. "VIKTOR").

variables:
- group: VIKTOR  # variable group within DevOps library containing the variables VIKTOR_DEV VIKTOR_TOKEN & VIKTOR_ENV
jobs:
- job: test
  container: python:3.12-bullseye
  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.12-bullseye
  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

note

Be sure to set the variables VIKTOR_DEV, VIKTOR_TOKEN and VIKTOR_ENV by creating secrets.

name: viktor-test-publish
on: push
env:
  VIKTOR_DEV: ${{ secrets.VIKTOR_DEV }}
  VIKTOR_TOKEN: ${{ secrets.VIKTOR_TOKEN }}
  VIKTOR_ENV: ${{ secrets.VIKTOR_ENV }}
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: 3.12
      - 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@v4
        with:
          python-version: 3.12
      - 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

note

Be sure to set the variables VIKTOR_DEV, VIKTOR_TOKEN and VIKTOR_ENV to the project's settings.

stages:
  - test
  - publish

image: python:3.12-bullseye

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

caution

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

version: 2
jobs:
  test:
    docker:
      - image: python:3.12-bullseye
    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

caution

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

language: python
python:
  - "3.12"

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

Continuous Integration/Deployment

Setting up the environment​

Continuous Integration​

Continuous Deployment​

Example CI/CD files​

Setting up the environment

Continuous Integration

Continuous Deployment

Example CI/CD files