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

config:
  repo: 'mar10/test-release-tool'
  gh_auth:
    oauth_token_var: GITHUB_OAUTH_TOKEN
  version:
    - type: __version__
      file: src/test_release_tool/__init__.py
  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.

Tasks

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 setup.py 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
  targets:
    - sdist
    - bdist_wheel

clean (bool), default: true

Run python setup.py 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:

--dry-run

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 setup.py --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:

--dry-run

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

--inc

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

--force

Bump version even if the max_increment rule would be violated.

--force-pre-bump

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

--no-bump

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           # `setup.py --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 <https://packaging.python.org/en/latest/specifications/pypirc/> exists, and the package is registered at PyPI <https://pypi.org/>.
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 setup.py --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:

--no-check

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:

--dry-run

Pass --dry-run to git commands.

‘exec’ Task

Run a shell command using subprocess.run(), 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:

--dry-run

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}

    [Changelog](https://github.com/{repo}/blob/master/CHANGELOG.md),
    [Commit details](https://github.com/{repo}/compare/{org_tag_name}...{tag_name}).
  prerelease: null  # null: guess from version number format
  upload:
    - 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:

--dry-run

Do not actually call the GitHub API request.

--gh-draft

Force github_release.draft: true.

--gh-pre

Force github_release.prerelease: true.

--no-release

Skip this task.

Preconditions

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:

--dry-run

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:

--dry-run

description.

--no-release

Skip this task.

Preconditions

• 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:

--dry-run

description.

‘winget_release’ Task

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

- task: winget_release
  upload: 'bdist_msi'
  package_id: 'foo.bar'
  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:

--dry-run

description.