Script Reference#

Workflow Configuration#

At the beginning of the configuration file, we define general options for all following tasks in this workflow:

file_version: yabs#1

  repo: 'mar10/test-release-tool'
    oauth_token_var: GITHUB_OAUTH_TOKEN
    - type: __version__
      file: src/test_release_tool/
  max_increment: minor
  branches:  # Current branch must be in this list
    - main  # Used by GitHub since 2020-11
    - master  # legacy
branches (str | list), default: null

Git branch name (or list of such) that are allowed.
This check is typically used to prevent creating accidental releases from feature or maintenance branches.

gh_auth (dict | str), mandatory

Name of the environment variable that contains your GitHub OAuth token :

oauth_token_var (str)

oauth_token_var: GITHUB_OAUTH_TOKEN

max_increment (str)

Restrict the maximum bump-increment.
The supported increments have this order:
‘postrelease’ < ‘prerelease’ < ‘patch’ < ‘minor’ < ‘major’.
For an example, a value of ‘patch’ will prevent ‘minor’ or ‘major’ bumps, which may be handy to prevent accidental releases from maintenance branches.
Passing --force on the command line will allow to ignore this setting.

repo (str), mandatory

GitHub repository name in the form ‘USER/REPO’, for example ‘mar10/test-release-tool’.

version (dict)

Define the location of the project’s version number.
See Version Locations for details.


Common Task Options#

All tasks share these common arguments (see also WorkflowTask):

dry_run (bool), default: false

Run this task without really writing changes. This task-flag overrides the global mode, which is enabled using the --dry-run (or -n) argument.

verbose (int), default: 3

Set log verbosity level in the range of quiet (0) to very verbose (5). This task-flag overrides the global mode, which is incremented/decremented using the --verbose/--quiet (or -n/-q) arguments.

‘build’ Task#

This task calls python TARGET to create Python builds. The artifacts are then typically used by following tasks like pypi_release.
Technically, the files are first created in a temporary folder and then moved to the project’s /dist folder:

- task: build
    - sdist
    - bdist_wheel
clean (bool), default: true

Run python clean --all after the builds were created on order to cleanup the build/ folder.

revert_bump_on_error (bool), default: true

Un-patch a previously bumped version number if an error occurred while running this build task. This may make it a bit easier to recover and cleanup manually.

targets (list), default: [‘sdist’, ‘bdist_wheel’]

Valid targets are “sdist”, “bdist_wheel”, and “bdist_msi”.

Command Line Arguments:


Build artifacts to temp folder, but do not copy them to dist/.

‘bump’ Task#

This task increments the project’s version number according to SemVer by patching the respective text file. Please read Version Locations and After-Release Versions for details.
Example: bump version according to the --inc command line argument:

- task: bump
  inc: null

Bump version for after-release status:

- task: bump
  inc: postrelease
  prerelease_prefix: "a"
  prerelease_start_idx: 1
check (bool), default: true

If true, python --version is called after bumping the version and an error is raised if it does not match the expected value.

inc (str|null), default: null

If null, the value that was passed as --inc argument on the command line is used.
Otherwise the value must be one of major, minor, patch, postrelease, or prerelease.

prerelease_prefix (str), default: “a”

This value is used to prefix pre- or post-release version numbers. For example if "a" (the default) is passed, the pre-release version for 1.2.3 could be 1.2.3-a1.

prerelease_start_idx (int), default: 1

This value is used to prefix pre- or post-release version numbers. For example if 0 is passed, the pre-release version for 1.2.3 would be 1.2.3-a0.

Command Line Arguments:


Calculate, but do not write the new version to the target file.


Define the SemVer increment (‘postrelease’, ‘prerelease’, ‘patch’, ‘minor’, or ‘major’).
This arguemnt is only considered if the task defines the inc: null option.


Bump version even if the max_increment rule would be violated.


Bump –inc postrelease even if the current version is untagged.


Skip all bump tasks by forcing them to dry-run mode.

‘check’ Task#

This task will test a bunch of preconditons and stop the workflow if one or more checks fail.

- task: check
  build: true             # dist/ folder exists
  can_push: true          # Test if 'git push' would succeed
  clean: true             # Repo must/must not contain modifications
  github: true            # GitHub repo name valid and online accessible
  os: null                # (str, list)
  pypi: true              # `twine` is available, PyPI package accessible
  python: ">=3.9"         # SemVer specifier
  up_to_date: true        # everything pulled from remote
  venv: true              # running inside a virtual environment
  version: true           # ` --version` returns the configured version
  winget: true            # `wingetcreate` is available
  yabs: ">=0.5"           # SemVer specifier
build (bool), default: true

Test if ./dist folder exists.

can_push (bool), default: true

Test if git push --dry-run would succeed.

clean (bool), default: true

Test if the index or the working copy is clean, i.e. has no changes.

github (bool), default: true

Test if the GitHub repository is accessible. This implies that

  • An internet connection is up

  • GitHub is reachable

  • The GitHub OAuth token (config.gh_auth.oauth_token_var option) is valid

  • The repository name (config.repo option) exists and is accessible

os (str | list), default: null

Test if the return value of platform.system() is in the provided list.
Typical values are ‘Linux’, ‘Darwin’, ‘Java’, ‘Windows’.

pypi (bool), default: true

Test if twine is available, ~/.pypirc <> exists, and the package is registered at PyPI <>.
This is required by the pypi_release task.

python (str), default: null

Test if the current Python version matches the provided specification.
Example python: '>=3.9'

repo (str), default: (value from config.repo)

Allows to override the global setting.

up_to_date (bool), default: true

Test if the remote branch contains unpulled changes, by calling git status -uno.

venv (bool), default: true

Test if yabs is running inside a virtual environment.

version (bool), default: true

Test if the result of python --version matches the version that yabs read from the configured version location.

winget (bool), default: null (depends)

Test if wingetcreate.exe is installed (required by winget_release task).
Also pre-releases will be flagged.

If null or undefined, this test is activated if a winget_release task is present and –no-winget is not passed.

yabs (str), default: null

Test if the installed Yabs version matches the provided specification.
Example yabs: '>=0.5'

Command Line Arguments:


Print warnings but continue workflow even if one or more checks failed.

‘commit’ Task#

Commit modified files using git commit:

- task: commit
  add_known: true
  message: |
    Bump version to {version}
add (list), default: []

Optional list of files and patterns to add to the index.

add_known (bool), default: true

Commit with –all option (commit all changed files).

message (str), default: ‘Bump version to {version}’

Commit message.
Context macros are expanded, e.g. ‘{version}’, … See Template Macros for details.
Tip: when using Travis, a ‘[ci skip]’ substring tells travis to ignore this commit.

Command Line Arguments:


Pass --dry-run to git commands.

‘exec’ Task#

Run a shell command using, for example tox -e lint:

- task: exec
  args: ["tox", "-e", "lint"]
  always: true            # `true`: run even in dry-run mode
  silent: true            # `true`: suppress final printing of process output
  ignore_errors: false    # `true`: show warning, but proceed on errors (exit code != 0)
  timeout: 60.0           # Kill process after <n> seconds

add_artifacts (dict), default: null

Check folder for files that were created by the shell command and add them as artifact for downstream tasks.

  • add_artifacts: # Add new files if any folder: “dist” matches: bdist_msi: ‘.*.msi’

args (list), mandatory

List of command line parts.

always (bool), default: false

If true, this command will also be run in dry-run mode.

dry_run_args (list), default: null

List of command line parts that will be used instead of the exec.args option when dry-run mode is active.
Otherwise in dry-run mode only the command line args are printed.

ignore_errors (bool), default: false

If true, error code != 0 will be ignored (yabs would stop otherwise).

log_start (bool), default: true

If true, ‘Running xxx…’ is printed before calling the actual script.

silent (bool), default: false

Controls whether the process output will be printed to the console after the command finished.
false: Always print output after the command finished.
true: Print output only when errors occured (return code != 0).
NOTE: A summary line is always printed.
NOTE: For long-running tasks, streamed: true may be a better option.

streamed (bool), default: null

Poll and log output while the process is running.
true enable polling (mutually exclusive with silent: false).
false disable polling.
null assume true if verbose mode is on.

timeout (float), default: null

Kill the subprocess after timeout seconds.

Command Line Arguments:


Do not execute the shell command (see also always and dry_run_args above).

‘github_release’ Task#

Use the GitHub API to create a release from the tag and artifacts that yabs created in previous tasks:

- task: github_release
  name: 'v{version}'
  message: |
    Released {version}

    [Commit details]({repo}/compare/{org_tag_name}...{tag_name}).
  prerelease: null  # null: guess from version number format
    - sdist
    - bdist_wheel
gh_auth (dict), default: null

Optionally override the global config.gh_auth setting.

draft (bool), default: false

true: create a draft (unpublished) release
false: to create a published one.
Use the --gh-draft argument to override.

message (str), default: ‘(see example above)’

Description of the release. See also Template Macros.

name (str), default: ‘v{version}’

The name of the new release. See also Template Macros.

prerelease (bool), default: null

false: mark as full release.
true: mark as pre-release, i.e. not ready for production and may be unstable.
null: guess from version number, i.e. post-release numbers containing ‘-’ are considered pre-releases.
Use the --gh-pre to argument to override.

repo (str), default: null

Optionally override the global config.repo setting.

target_commitish (str), default: null

Specifies the commitish value that determines where the Git tag is created from. Can be any branch or commit SHA. Unused if the Git tag already exists.
Default: the repository’s default branch (usually master).

upload (list), default: null

List of artifact names (‘sdist’, ‘bdist_wheel’, and ‘bdist_msi’).
Default null: upload all artifacts that were created in the previous build-task.

Command Line Arguments:


Do not actually call the GitHub API request.


Force github_release.draft: true.


Force github_release.prerelease: true.


Skip this task.


A tag and build task must be run first.

‘push’ Task#

Call git push to push changes and tags:

- task: push
  tags: true
tags (bool), default: false

Use --follow-tags to push annotated tags as well.

target (str), default: ‘’

Defines the push target.
By default, the ‘branch.*.remote’ configuration for the current branch is consulted. If the configuration is missing, it defaults to ‘origin’.

Command Line Arguments:


Pass ‘–dry-run’ option to ‘git push’ command.

‘pypi_release’ Task#

Call twine upload create a release on PyPI from the artifacts that yabs created in previous tasks:

- task: pypi_release
comment (str), default: null

Optional string passed as twine –comment COMMENT ….

upload (list), default: null

List of artifact names (‘sdist’, ‘bdist_wheel’, and ‘bdist_msi’).
Default null: upload all artifacts that were created in the previous build-task.

Command Line Arguments:




Skip this task.


  • A tag and build task must be run first.

  • twine must be available.

‘tag’ Task#

Call git tag to create an annotated tag:

- task: tag
  name: v{version}
  message: |
    Version {version}
message (str), default: ‘Version {version}’

The description of the new tag. See also Template Macros.

name (str), default: ‘v{version}’

The name of the new tag. See also Template Macros.

Command Line Arguments:



‘winget_release’ Task#

Call wingetcreate update to update an existing release on winget-pkgs:

- task: winget_release
  upload: 'bdist_msi'
  package_id: ''
  assume_synced: false
assume_synced (bool), default: false

If true, skip warning about outdated fork.

package_id (str)

Package id in the WPM repo. Typically USER.PROJECT.

upload (str), default: ‘bdist_msi’

The artifact-id that was created using an upstream exec task.

Command Line Arguments: