Workflows

Your Salt extension repository includes several workflows out of the box if your source_url is on GitHub.

Provided functions

The workflows currently:

  • Ensure pre-commit checks pass

  • Run the test suite and upload code coverage reports

  • Build the documentation

  • Build the changelog and submit a PR that triggers a release when merged

  • Optionally deploy built documentation to GitHub Pages

  • Optionally build and release your project to PyPI

Repository setup

Required settings (all)

GitHub Pages

If publishing documentation to GitHub Pages, ensure you have set up your repository to allow deployments from GitHub Actions.

Release automation

Also, ensure GitHub Actions are allowed to create PRs to take advantage of the release automation. In the organization, this should be enabled by default.

In your repository settings, click on Actions > General, scroll down and ensure Allow GitHub Actions to create and approve pull requests is checked.

Required secrets (non-org)

If your repository is not hosted within the salt-extensions organization, you need to ensure the project can be published to PyPI. You can either setup legacy API tokens or configure a Trusted Publisher on PyPI.

Trusted Publisher

To configure a Trusted Publisher, head over to PyPI and login. Click on your user name in the top right corner, then Your projects. In the left menu, select Publishing. Scroll down until you see Add a new pending publisher. Select GitHub (should be selected by default). Specify a PyPI project name, the name of the GitHub organization/user account that owns the repository and the repository name. As Workflow name, fill in deploy-package-action.yml.

Repeat the above steps for test.pypi.org.

Note

Reusable workflows, as employed in generated projects, are not fully supported as a Trusted Publisher at the moment. Specifically, attestations cannot be uploaded.

Legacy API token

Alternatively, you can add the following secrets:

PYPI_API_TOKEN

An API token for PyPI for releasing your Saltext.

TEST_PYPI_API_TOKEN

An API token for TestPyPI for testing the release of your Saltext.

Important artifacts

After a workflow run, several artifacts are available for download on the action summary page (scroll down).

runtests-*.log

Contains logs generated during a specific test run, useful for debugging test failures.

html-docs

The built HTML documentation, also available for preview when triggered by a Pull Request.

Workflows call stack

  1. .github/workflows/pr.yml or .github/workflows/tag.yml is triggered

  2. .github/workflows/ci.yml is called as the main entry point to CI

  3. Depending on the event and inputs, select additional workflows perform the necessary tasks.