Documentation
Start typing to search…

CI/CD Environment

How to use the Popul8 CLI in a CI/CD environment

This guide shows how to automate Popul8 Express in GitLab CI with a Windows runner.

Prerequisites

  • A GitLab Runner on Windows (Shell or PowerShell executor), tagged (e.g., windows).
    See GitLab's Windows Runner installation guide.
  • Popul8 Express installed on the Windows runner (e.g., C:\Program Files (x86)\Popul8\Popul8.exe or the default install path).
    See Windows long path support if you encounter path issues.
  • popul8-cli.exe available in PATH, or use its absolute path in scripts.
  • A valid license file accessible by the runner.

Environment variables (recommended)

Define the following variables in GitLab CI settings (masked/protected as needed):

  • POPUL8_PATH: Path to Popul8 application, e.g., C:\\Program Files (x86)\\Popul8\\Popul8.exe
  • POPUL8_LICENSE_PATH: Path to license file, e.g., C:\\builds\\licenses\\license.bin
  • POPUL8_PORT: Port number for the CLI to communicate with Popul8, e.g., 2055

Optional variables for project automation:

  • POPUL8_PROJECT_PATH: Path to your .pp8 project file
  • POPUL8_EXPORT_DIR: Export output directory
  • POPUL8_VERIFY_DIR: Verify output directory

For complete details on all CLI commands and options, see the Popul8 CLI documentation.

General CI flow

This section outlines the typical workflow for automating Popul8 in CI/CD. The example configuration below demonstrates these steps in practice.

  1. Start Popul8 - Launch the Popul8 application using popul8-cli start.
    Optionally set he path to the executable and desired port.
  2. Configure license - Set or verify the license file using popul8-cli license.
    You can provide a path to set a new license, or run without arguments to check the current license status.
  3. Open a project (.pp8) - Load your Popul8 project file using popul8-cli open <path-to-project.pp8>
  4. Export or Verify
    • Use popul8-cli export <output-dir> to export assets from your project . Change export mode by adding the optional flag --bridge or --single.
    • Use popul8-cli verify <output-dir> to run verification checks and export verified assets.
      Add optional --scope parameter to control what is verified: templates, shapes, or all.
  5. Collect artifacts - Configure your CI system to save the output directories as build artifacts
  6. Stop Popul8 - Shut down the Popul8 application using popul8-cli stop

Windows GitLab CI example

The example below uses a Windows Shell/PowerShell runner. Adjust paths, tags, and variables to your environment.

stages:
  - export
  - verify

.variables_base: &variables_base
  POPUL8_CLI: "C:\\Program Files (x86)\\Popul8\\popul8-cli.exe"
  POPUL8_PATH: "C:\\Program Files (x86)\\Popul8\\Popul8.exe"
  POPUL8_LICENSE_PATH: ""
  POPUL8_PORT: "2055"
  POPUL8_PROJECT_PATH: "$CI_PROJECT_DIR\\DemoExpress.pp8"
  POPUL8_EXPORT_DIR: "$CI_PROJECT_DIR\\export_results"
  POPUL8_VERIFY_DIR: "$CI_PROJECT_DIR\\verify_results"

.default_windows: &default_windows
  tags: ["windows"]
 
export_assets:
  stage: export
  <<: *default_windows
  variables:
    <<: *variables_base
  script:
    - |
      "$POPUL8_CLI" --version
      "$POPUL8_CLI" start "$POPUL8_PATH" -p "$POPUL8_PORT" --gui
      echo "Popul8 started"
      echo "Setting license..."
      "$POPUL8_CLI" license "$POPUL8_LICENSE_PATH" -p "$POPUL8_PORT"
      echo "Opening project..."
      "$POPUL8_CLI" open "$POPUL8_PROJECT_PATH" -p "$POPUL8_PORT"
      echo "Project opened"
    - |
      echo "Creating export directory..."
      mkdir -p "$POPUL8_EXPORT_DIR"
      echo 'Exporting assets...'
      "$POPUL8_CLI" export "$POPUL8_EXPORT_DIR" -p "$POPUL8_PORT"
      echo "Export completed"
    - |
      echo "Stopping Popul8..."
      "$POPUL8_CLI" stop -p "$POPUL8_PORT"
  artifacts:
    when: always
    expire_in: 1 week
    paths:
      - export_results/
  rules:
    - when: on_success

verify_assets:
  stage: verify
  <<: *default_windows
  variables:
    <<: *variables_base
  script:
    - |
      "$POPUL8_CLI" --version
      "$POPUL8_CLI" start "$POPUL8_PATH" -p "$POPUL8_PORT" --gui
      echo "Popul8 started"
      echo "Setting license..."
      "$POPUL8_CLI" license "$POPUL8_LICENSE_PATH" -p "$POPUL8_PORT"
      echo "Opening project..."
      "$POPUL8_CLI" open "$POPUL8_PROJECT_PATH" -p "$POPUL8_PORT"
      echo "Project opened"
    - |
      echo "Creating verify directory..."
      mkdir -p "$POPUL8_VERIFY_DIR"
      echo "Verifying assets..."
      "$POPUL8_CLI" verify "$POPUL8_VERIFY_DIR" -p "$POPUL8_PORT" --scope templates -v
      echo "Verification completed"
    - |
      echo "Stopping Popul8..."
      "$POPUL8_CLI" stop -p "$POPUL8_PORT"
  artifacts:
    when: always
    expire_in: 1 week
    paths:
      - verify_results/
  rules:
    - when: on_success

Notes & Troubleshooting

  • If Popul8 Express is not found or fails to start, start will fail; ensure POPUL8_PATH is correct or use auto with a previously saved config (popul8-cli config --popul8path).
  • On Windows, long paths require quoting ("C:\path with spaces\file.pp8").
  • license without a path shows current status; provide a path to set/update.
  • Use separate jobs for export and verify to keep artifacts isolated.

Related Documentation

Aditional GitLab CI/CD documentation

Updated 25 days ago