Write your deployment scenario¶

What is a scenario?¶

This is the main way to use QDT. You write your deployment scenario by describing the steps to be done to prepare the QGIS environment, take a coffee (cup of tea is also tolerated) and look at the scenario running.

In concrete terms, a scenario is a YAML file whose extension (.yaml or .yml) can be suffixed with .qdt so as to be more easily distinguished by the tool in the midst of potential other YAML files. Example: scenario.qdt.yml. The syntax is largely inspired by DevOPS oriented tools like Ansible or CI/CD platforms (GitHub Actions, GitLab CI in particular).

A scenario has 3 sections:

metadata: to describe the scenario (title, description, etc.)
settings: to set execution parameters to be applied to QDT, in the form of keys/values
steps: the steps that the deployment scenario will successively take. Each step can call for a “job”.

By default, QDT looks for a file named scenario.qdt.yml in the current directory.
If it is not found, it will expect subcommands to run.

Jobs¶

A job is a logical module that is called by a step in a scenario, by passing it parameters. Concretely, each job is a Python module of QDT (here in the code).

A step consists of 3 elements:

name: the name of the step
uses : the job identifier to use
with` : the parameters to pass to the Job

See available jobs

Tip

Editing a scenario file can be tricky and since it’s a critical piece of the QDT workflow, the project provide some tooling to help writing and checking them: How to automatically validate QDT files.

Sample scenario¶

For development and test purposes, project provides a sample scenario:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Guts/qgis-deployment-cli/main/docs/schemas/scenario/schema.json

# This is a sample of a YAML file for the QGIS Deployment Toolbelt scenario.
# For now, it's more a roadmap than a real description of what it's implemented.

metadata:
  title: "Test scenario of QGIS Deployment Toolbelt"
  id: test-basic-scenario-good
  description: >-
    This is an example a scenario YAML file for the QGIS Deployment Toolbelt to
    demonstrate capabilities.

settings:
  DEBUG: false
  LOCAL_WORK_DIR: ~/.cache/qgis-deployment-toolbelt/tests/
  SCENARIO_VALIDATION: true

steps:
  - name: Set environment variables
    uses: manage-env-vars
    with:
      - name: TEST_PYQGIS_STARTUP
        action: "add"
        value: "~/scripts/qgis_startup.py"
        scope: user
      - name: TEST_FAKE_BOOL
        action: "add"
        scope: user
        value: false
        value_type: bool

  - name: Download profiles from remote git repository
    uses: qprofiles-downloader
    with:
      source: https://github.com/Guts/qgis-deployment-cli.git
      protocol: git_remote
      branch: main

  - name: Synchronize downloaded profiles with installed ones
    uses: qprofiles-synchronizer
    with:
      sync_mode: only_new_version

  - name: Download plugins
    uses: qplugins-downloader
    with:
      force: false
      threads: 5

  - name: Synchronize plugins
    uses: qplugins-synchronizer
    with:
      action: create_or_restore
      profile_ref: downloaded

  - name: Create shortcuts for profiles
    uses: shortcuts-manager
    with:
      action: create_or_restore
      include:
        - profile: qdt_demo
          label: "TEST QDT - Demo profile"
          desktop: true
          start_menu: true
        - profile: QDT Viewer Mode
          label: "TEST QDT - Viewer profile"
          desktop: true
          start_menu: true

  - name: Set splash screen
    uses: splash-screen-manager
    with:
      action: create_or_restore
      strict: false