The documentation you're currently reading is for version 2.5.1. Click here to view documentation for the latest stable version.
Pack Management Transition¶
In 2.1, with the introduction of the new pack management and StackStorm Exchange, BWC validates pack metadata in
enforces certain versioning and naming conventions. These changes may require users to update
their custom Packs.
All packs in StackStorm Exchange have been updated to work with BWC 2.1 and maintain compatibility with older versions.
In BWC 2.1, pack management has received a significant overhaul. With new dedicated tools, working with packs becomes very close to the “usual” package management you know from working with development platforms and Linux flavors. Installing, updating, and managing StackStorm packs has become a smoother, more streamlined experience.
It’s a big change, and you will surely enjoy how easy it is to install and maintain your packs now, especially if you’re upgrading from an earlier version. Installing packs, contributing fixes, handling pack versions, sharing and discovering — nearly everything about StackStorm packs is better than before.
Some of the changes require special attention: if you create your own packs or deploy packs from
st2contrib — either through configuration management or by running
st2 run packs.install as
a part of your deployment — please read this section carefully.
StackStorm Exchange is a new pack directory maintained by
the StackStorm team. Any pack from the Exchange can be installed with
st2 pack install <pack>.
Exchange packs are hosted in the
on GitHub, and you can open PRs against them just as you would open PRs to
before. To submit a new pack, follow the instructions in
All packs from st2contrib have been transferred to individual repositories inside the StackStorm-Exchange organization. The st2contrib repository is frozen: it is still functional, but it will not receive updates anymore, and new submissions are not accepted.
You can host your own pack index alongside (or even instead of) the Exchange, and get your BWC content from multiple indexes. See “Advanced topics” in Packs for instructions.
Using StackStorm Exchange with pre-2.1 BWC¶
If you use BWC 2.0 or earlier, you can still get packs from
StackStorm Exchange with the old
stackstorm-exchange/<pack name> as
repo_url, and repeat the pack name in
As an example, for the Cloudflare pack, the full CLI command would be:
$ st2 --version st2 2.0.1 $ st2 run packs.install packs=cloudflare repo_url=stackstorm-exchange/cloudflare
Alternatively, you can just
git clone the packs, making sure that the pack directory name
matches the pack
cd /opt/stackstorm/packs git clone https://github.com/StackStorm-Exchange/stackstorm-cloudflare.git cloudflare chown -R root:st2packs cloudflare st2 run packs.setup_virtualenv packs=cloudflare st2ctl reload
Starting from 2.1, BWC enforces validation on
If you create your own packs, please validate them against these rules:
pack.yamlmust conform to semver:
0.2. Pack loading will fail if the version is not in semver format.
pack.yamlmust only contain letters, digits, and underscores, since it is also used as a ref (UID) for the pack. You can set the
refvalue explicitly in
pack.yaml: in this case,
refis going to be validated against the rule above, and
nameis going to be used for display only and can contain any characters.
- The email attribute in
pack.yamlmust contain a properly formatted email address.
Make sure your custom packs are compatible, then follow the steps in Upgrade Notes to upgrade to 2.1. All packs in the Exchange have been updated to reflect these changes.
Git Repositories for Packs¶
st2 pack install <URL>, the URL is assumed to be a valid git repository containing
your pack in its root (see StackStorm-Exchange on GitHub).
This structure is required to support most of the newer pack management features, and we strongly
encourage pack developers to follow it. However, if your deployment is different (maybe you don’t
git, or place multiple packs in a repository, or install packs through a configuration
management tool), you aren’t required to use the
st2 pack subcommands at all: refer to the
“Under the Hood: Pack Basics” section of the pack documentation.
Subtree repositories (repositories containing multiple packs inside the
packs/ subdir) are no
longer supported, and the
subtree parameter in
packs.install is removed. If you happen to
use a single repository to host multiple packs, it will have to be split into multiple single-pack
repositories in order for
st2 pack install to be able to install the packs. Alternatively,
deploy them manually as described above.
Changes to Take Advantage Of¶
Read the Pack management doc to learn more about the new pack management.
- A new
pack installcommand supports getting the specific version, hash, branch, or tag of a pack.
- A new
pack confighelps create, validate, and load pack configurations conforming to new Pack Configuration.
- CLI and API for pack discovery: you can search the pack directory right from the CLI.
- You can specify
pack.yaml: it should contain a version range to determine if the installed version of BWC is compatible with your pack (e.g.
>=1.6.0, <2.0.0, or just
>1.6.0). If your pack relies on functionality which is only available in newer versions of StackStorm, we encourage you to specify the correct range.
- You can specify
pack.yaml: it is an array that should contain a list of people who have contributed to the pack. These days most of the packs have more than one contributor, and the
authorfield just isn’t enough to give credit where credit is due.
- A pack is no longer named and referenced by its parent directory or git source: the
ref, if specified) field from
pack.yamlwill be used. The repository name is entirely up to you (a convention we use in StackStorm Exchange is