Command line and parameters

Univesrum can be executed via python3.8 -m universum with various parameters. These parameters can be passed via command line; most of them can also be passed via environment variables.

Apart from default mode, actually used for CI, Universum also has several other helpful modes and a bunch of analyzers that are used to add comments on found issues right to the selected code review system.

Universum 0.19.19

usage: python3.8 -m universum [-h] [--version] [--build-only-latest]
                              [--no-diff] [--fail-unsuccessful]
                              [--out-type {tc,term,jenkins,github}]
                              [--html-log [OUTPUT.HTML_LOG]]
                              [--report-to-review] [--vcs-type VCS_TYPE]
                              [--project-root PROJECT_ROOT]
                              [--file-source-dir SOURCE_DIR]
                              [--git-checkout-id GIT_CHECKOUT_ID]
                              [--git-cherry-pick-id GIT_CHERRYPICK_ID [GIT_CHERRYPICK_ID ...]]
                              [--git-repo GIT_REPO]
                              [--git-refspec GIT_REFSPEC]
                              [--report-build-start] [--report-build-success]
                              [--report-only-fails]
                              [--report-only-fails-short] [--report-no-vote]
                              [--server-type {tc,jenkins,local}]
                              [--tc-server TEAMCITY_SERVER]
                              [--tc-build-id BUILD_ID]
                              [--tc-configuration-id CONFIGURATION_ID]
                              [--tc-auth-user-id TC_USER]
                              [--tc-auth-passwd TC_PASSWD]
                              [--jenkins-build-url BUILD_URL]
                              [--github-server GITHUB_SERVER_URL]
                              [--github-repo GITHUB_REPOSITORY]
                              [--github-run-id GITHUB_RUN_ID]
                              [--ghapp-check-name GITHUB_CHECK_NAME]
                              [--gapp-check-id GITHUB_CHECK_ID]
                              [--ghapp-api-url GITHUB_API_URL]
                              [--ghapp-installation-id GITHUB_INSTALLATION_ID]
                              [--ghapp-app-id GITHUB_APP_ID]
                              [--ghapp-private-key GITHUB_PRIVATE_KEY]
                              [--ghactions-token GITHUB_TOKEN]
                              [--ghactions-payload GITHUB_PAYLOAD]
                              [--p4-client P4CLIENT]
                              [--p4-sync SYNC_CHANGELIST [SYNC_CHANGELIST ...]]
                              [--p4-shelve SHELVE_CHANGELIST [SHELVE_CHANGELIST ...]]
                              [--p4-force-clean]
                              [--p4-project-depot-path P4_PATH]
                              [--p4-mappings P4_MAPPINGS [P4_MAPPINGS ...]]
                              [--p4-port P4PORT] [--p4-user P4USER]
                              [--p4-password P4PASSWD]
                              [--swarm-server-url SWARM_SERVER]
                              [--swarm-review-id REVIEW]
                              [--swarm-change SWARM_CHANGELIST]
                              [--swarm-pass-link PASS]
                              [--swarm-fail-link FAIL]
                              [--swarm-review-versn REVIEW_VERSION]
                              [--artifact-dir ARTIFACT_DIR] [--no-archive]
                              [--out {console,file}] [--config CONFIG_PATH]
                              [--filter STEP_FILTER]
                              {init,run,poll,submit,github-handler} ...

Named Arguments

--version

Display product name & version instead of launching.

--build-only-latest

Skip build if review version isn’t latest

Default: False

--no-diff

Only applies to build steps where code_report=True; disables calculating analysis diff for changed files, in this case full analysis report will be published

Default: False

--fail-unsuccessful

Return non-zero exit code if any step failed

Default: False

Output

Log appearance parameters

--out-type, -ot

Possible choices: tc, term, jenkins, github

Type of output to produce (tc - TeamCity, jenkins - Jenkins, term - terminal, github - Github Actions). TeamCity, Jenkins and Github Actions environments are detected automatically when launched on build agent.

--html-log, -hl

Generate a self-contained user-friendly HTML log. Pass a desired log name as a parameter to this option, or a default ‘universum_log.html’ will be used.

To make sure all the interactive features of such a page work right in Jenkins artifacts, please refer to the following guide

--out, -o

Possible choices: console, file

Define whether to print build logs to console or file. Log file names are generated based on the names of build steps. By default, logs are printed to console when the build is launched on Jenkins or TeamCity agent

Source files

--report-to-review

Perform test build for code review system (e.g. Gerrit or Swarm).

Default: False

--vcs-type, -vt

Possible choices: none, p4, git, gerrit, ghapp, ghactions

Select repository type to download sources from: Perforce (‘p4’), Git (‘git’), Gerrit (‘gerrit’), GitHub App (‘ghapp’), GitHub Actions (‘ghactions’), or a local directory (‘none’). Gerrit uses Git parameters. Each VCS type has its own settings.

Environment variable: $VCS_TYPE

--project-root, -pr

Temporary directory to copy sources to. Default is ‘temp’

Environment variable: $PROJECT_ROOT

Local files

Parameters for file settings in case of no VCS used

--file-source-dir, -fsd

A local folder for project sources to be copied from. This option is only needed when ‘–driver-type’ is set to ‘none’

Environment variable: $SOURCE_DIR

Git

--git-checkout-id, -gco

A commit ID to checkout. Could be exact commit hash, or branch name, or tag, etc.

Environment variable: $GIT_CHECKOUT_ID

--git-cherry-pick-id, -gcp

List of commit IDs to be cherry-picked, separated by comma. ‘–git-cherry-pick-id’ can be added to the command line several times

Environment variable: $GIT_CHERRYPICK_ID

--git-repo, -gr

See your project home page for exact repository identifier, passed to ‘git clone’. If using SSH, ‘–git-repo’ format is ‘ssh://user@server:port/detailed/path’

Environment variable: $GIT_REPO

--git-refspec, -grs

Any additional refspec to be fetched

Environment variable: $GIT_REFSPEC

Result reporting

Build results collecting and publishing parameters

--report-build-start, -rst

Send additional comment to review system on build started (with link to log)

Default: False

--report-build-success, -rsu

Send comment to review system on build success (in addition to vote up)

Default: False

--report-only-fails, -rof

Include only the list of failed steps to reporting comments

Default: False

--report-only-fails-short, -rofs

Include only the short list of failed steps to reporting comments

Default: False

--report-no-vote, -rnv

Do not vote up/down review depending on result

Default: False

Automation server

Automation server options

--server-type, -st

Possible choices: tc, jenkins, local

Type of environment to refer to (tc - TeamCity, jenkins - Jenkins, local - user local terminal). TeamCity and Jenkins environment is detected automatically when launched on build agent

TeamCity variables

TeamCity-specific parameters

--tc-server, -ts

TeamCity server URL

Environment variable: $TEAMCITY_SERVER

--tc-build-id, -tbi

teamcity.build.id

Environment variable: $BUILD_ID

--tc-configuration-id, -tci

system.teamcity.buildType.id

Environment variable: $CONFIGURATION_ID

--tc-auth-user-id, -tcu

system.teamcity.auth.userId

Environment variable: $TC_USER

--tc-auth-passwd, -tcp

system.teamcity.auth.password

Environment variable: $TC_PASSWD

Jenkins variables

Jenkins-specific parameters

--jenkins-build-url, -jbu

Link to build on Jenkins (automatically set by Jenkins)

Environment variable: $BUILD_URL

GitHub Actions variables

GitHub sets these environment variables and usually do not need to set these arguments. See: https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables

--github-server

GitHub server URL, used on GitHub Actions for constructing links to builds. For example: https://github.com

Environment variable: $GITHUB_SERVER_URL

--github-repo

GitHub owner and repository name, used on GitHub Actions for constructing links to builds. For example: octocat/Hello-World

Environment variable: $GITHUB_REPOSITORY

--github-run-id

GitHub run ID, used on GitHub Actions for constructing links to builds.For example: 1658821493

Environment variable: $GITHUB_RUN_ID

GitHub App

GitHub repository settings for application

--ghapp-check-name, -ghc

The name of Github check run

Environment variable: $GITHUB_CHECK_NAME

Default: “Universum check”

--gapp-check-id, -ghi

Github check run ID

Environment variable: $GITHUB_CHECK_ID

--ghapp-api-url, -gha

API URL for integration

Environment variable: $GITHUB_API_URL

Default: “https://api.github.com/”

--ghapp-installation-id, -gti

GitHub installation ID identifies specific app installation into user account or organization. Can be retrieved from web-hook or obtained via REST API; in standard workflow should be received from ‘universum github-handler’

Environment variable: $GITHUB_INSTALLATION_ID

--ghapp-app-id, -gta

GitHub application ID to use for check run report. Only GitHub App can report a check run result! If you don’t have an App for reporting purposes, please don’t use --report-to-review with GitHub

Environment variable: $GITHUB_APP_ID

--ghapp-private-key, -gtk

GitHub App private key for obtaining installation authentication token. Pass raw key data via environment variable or pass a file path to read the key from by starting the value string with ‘@’. File path can be either absolute or relative. Please note, that when passing a file, it is expected to be in UTF-8 encoding

Environment variable: $GITHUB_PRIVATE_KEY

GitHub Actions

GitHub repository settings for GH Actions

--ghactions-token, -ght

Is stored in ${{ secrets.GITHUB_TOKEN }}

Environment variable: $GITHUB_TOKEN

--ghactions-payload, -ghp

File path: ${{ github.event_path }}

Environment variable: $GITHUB_PAYLOAD

Perforce

--p4-client, -p4c

P4 client (workspace) name to be created. Use ‘–p4-force-clean’ option to delete this client while finalizing

Environment variable: $P4CLIENT

--p4-sync, -p4h

Sync (head) CL(s). Just a number will be interpreted as united CL for all added VCS roots. To add a sync CL for specific depot/workspace location, write location in the same format as in P4_MAPPINGS with ‘@<CL number>’ in the end, e.g. ‘//DEV/Solution/MyProject/…@1234567’. To specify more than one sync CL for several locations, add ‘–p4-sync’ several times or split them with comma

Environment variable: $SYNC_CHANGELIST

--p4-shelve, -p4s

List of shelve CLs to be applied, separated by comma. –p4-shelve can be added to the command line several times. Also shelve CLs can be specified via additional environment variables: SHELVE_CHANGELIST_1..5

Environment variable: $SHELVE_CHANGELIST

--p4-force-clean

Revert all vcs within ‘–p4-client’ and delete the workspace. Mandatory for CI environment, otherwise use with caution

Default: False

--p4-project-depot-path, -p4d

Depot path to get sources from (starts with ‘//’, ends with ‘/…’Only supports one path. Cannot be used with ‘–p4-mappings’ option

Environment variable: $P4_PATH

--p4-mappings, -p4m

P4 mappings. Cannot be used with ‘–p4-project-depot-path’ option. Use the following format: ‘//depot/path/… /local/path/…’, where the right half is the same as in real P4 mappings, but without client name. Just start from client root with one slash. For more than one add several times or split with ‘,’ character

Environment variable: $P4_MAPPINGS

--p4-port, -p4p

P4 port (e.g. ‘myhost.net:1666’)

Environment variable: $P4PORT

--p4-user, -p4u

P4 user name

Environment variable: $P4USER

--p4-password, -p4P

P4 password (please note, this should be exactly password, not the ticket)

Environment variable: $P4PASSWD

Swarm

Parameters for performing a test run for pre-commit review

--swarm-server-url, -ssu

Swarm server URL; is used for additional interaction such as voting for the review

Environment variable: $SWARM_SERVER

--swarm-review-id, -sre

Swarm review number; is sent by Swarm triggering link as ‘{review}’

Environment variable: $REVIEW

--swarm-change, -sch

Swarm change list to unshelve; is sent by Swarm triggering link as ‘{change}’

Environment variable: $SWARM_CHANGELIST

--swarm-pass-link, -spl

Swarm ‘success’ link; is sent by Swarm triggering link as ‘{pass}’

Environment variable: $PASS

--swarm-fail-link, -sfl

Swarm ‘fail’ link; is sent by Swarm triggering link as ‘{fail}’

Environment variable: $FAIL

--swarm-review-versn, -srv

Swarm review version; is sent by Swarm triggering link as ‘{version}’

Environment variable: $REVIEW_VERSION

Artifact collection

Parameters of archiving and collecting of build artifacts

--artifact-dir, -ad

Directory to collect artifacts to. Default is ‘artifacts’

Environment variable: $ARTIFACT_DIR

--no-archive

By default all directories noted as artifacts are copied as .zip archives. This option turn archiving off to copy bare directories to artifact directory

Default: False

Configuration execution

External command launching and reporting parameters

--config, -cfg

Path to project configuration file (example: -cfg=my/project/my_conf.py). Default is .universum.py

Environment variable: $CONFIG_PATH

--filter, -f

Allows to filter which steps to execute during launch.
String value representing single filter or a set of filters separated by ‘:’.
To define exclude pattern use ‘!’ symbol at the beginning of the pattern.

A Universum step match specified pattern when ‘filter’ is a substring of step ‘name’.
This functionality is similar to ‘boosttest’ and ‘gtest’ filtering, except special characters
(like ‘*’, ‘?’, etc.) are ignored.

Examples:
* -f=’run test’               - run only steps that contain ‘run test’ substring in their names
* -f=’!run test’              - run all steps except those containing ‘run test’ substring in their
names
* -f=’test 1:test 2’          - run all steps with ‘test 1’ OR ‘test 2’ substring in their names
* -f=’test 1:!unit test 1’    - run all steps with ‘test 1’ substring in their names except those
containing ‘unit test 1’

Additional commands

{init,run,poll,submit,github-handler}: See detailed description of additional commands here.