Publishing your Saltext

Important

This guide assumes your repository is hosted on GitHub.

There are currently no included workflows for other Git hosting providers or CI systems.

Once your Salt extension is ready, you can submit it to PyPI.

Ensure you meet the following prerequisites:

  • Your project is hosted on GitHub.

  • It is either in the salt-extensions organization or you have set up the required secrets and permissions.

  • You have commit rights to the repository.

Automated

Generated projects include a workflow that automatically detects the next version bump based on news fragments in changelog, builds the changelog and submits a PR with these changes. Once you are ready to release a new version, simply merge this PR, which creates a new git tag and triggers the release workflow.

Important

Before merging, ensure the PR is based on the current default branch HEAD.

Hint

To force a custom version or manually trigger an update to the release PR (e.g. to adjust the release date), go to Actions > Prepare Release PR > Run workflow.

Note

The generated PR is only created automatically if there is at least one news fragment to render. You can still trigger a manual run as described above.

Manual

0: Prerequisites

  • You have added a git remote upstream to your local repository, pointing to the official repository via SSH.

  • You have executed the first steps to setup your repository and virtual environment in some way.

  • You have activated your virtual environment.

Ensure your main branch is up to date:

git switch main && git fetch upstream && git rebase upstream/main

1: Build the changelog

Create and switch to a new branch:

git switch -c release/100

You have been keeping a changelog with towncrier, now is the time to compile it.

towncrier build --yes --version v1.0.0

This command combines all news fragments into CHANGELOG.md and clears them. Commit the change.

2: Submit the changelog

Submit this commit as a PR and merge it into the default branch on upstream.

Tip

Squash-merging this PR results in a cleaner tag target.

3: Tag a release

Ensure your main branch is up to date (again):

git switch main && git fetch upstream && git rebase upstream/main

Create a new tag named after the version:

git tag -s v1.0.0

Important

The tag must start with v for the default publishing workflows to work correctly.

Note

It’s recommended to create annotated (git tag -a) or signed (git tag -s) tags since they create an immutable git object. Regular tags are just pointers to a specific commit.

4: Push the tag

Push the new tag upstream to trigger the publishing workflow:

git push upstream v1.0.0

5: Check the result

If CI passes, a new release should be available on both PyPI and your GitHub repository.