Publish Policies to Artifact Hub
Kubewarden policies can be published on Artifact Hub and made discoverable to the wide audience of CNCF users.
Artifact Hub is a content aggregation platform and doesn't actually host the artifacts that are published on it.
Artifact Hub requires you to physically host container image repositories on a container registry or a web server. Refer to the "distributing policies" section for more information on how to host your policies.
This document focuses on the steps required to make a Kubewarden policy discoverable on Artifact Hub.
Prepare your Git repository
Artifact Hub crawls Git repositories looking for special metadata files.
There are different kind of layouts the Git repository can have. They are all documented in depth in the official Artifact Hub documentation.
Artifact Hub is pretty flexible and allows you to organize your code in these ways:
- Have a Git repository dedicated to Artifact Hub: this repository will not contain any policy source code. It will be a collection of the YAML files required by Artifact Hub.
- Add a Artifact Hub directory inside of the Git repository that holds the source of your policy. This is an iteration of the previous approach, the only difference is that it focuses just on one policy: the one defined inside of the Git repository. This approach allows to keep multiple versions of the policy published on Artifact Hub.
- Add the
artifacthub-repo.ymlfiles to the root of the Git repository that holds the policy source code. This approach is the simplest one. The only limitation is that only the latest version of the policy will be visible on Artifact Hub.
The last approach is what we used inside of our official policy templates.
The Git repository that is scaffolded includes the
Before publishing a policy to Artifact Hub, you must create an account on the website.
Before publishing the policy, ensure your Git repository has the proper layout.
artifacthub-pkg.yml contains fields such as
that need to match specific format, and be up-to-date. The format of the
artifacthub-pkg.yml is described
If you created the policy using one of our templates, then you have a
make artifacthub-pkg.yml target. Execute that target to generate the
artifacthub-pkg.yml file programmatically from
metadata.yml and other
inputs. This target gets called as part as a normal build of a policy, so
your task is to commit the resulting changes to
The policy templates make use of our GitHub Actions at github.com/kubewarden/github-actions:
- If you are using our GitHub Actions >=
v3.1.0, the workflows provide by default automated checking of the
- After a successful release, that is, after the policy has been successfully
built, signed, and pushed, our GitHub Actions have a last job that pushes the
files needed by Artifact Hub to an orphan
artifacthubbranch. The canonical files are always the ones in the
mainbranch, and the GHA job overwrites the ones in
artifacthubbranch every time.
Finally, ensure your policy is published inside of a container registry or on a web server.
Right now the contents of the
artifacthub-repo.yml file are not relevant.
Once everything is in place, log into Artifact Hub and go to your control plane.
Decide whether you want to publish the policy as a user or under an Artifact Hub organization you belong to. This is done by choosing the correct "control panel context".
Then press the "Add" button and fill the form:
- Choose "Kubewarden policies" as kind.
- Enter a "Name" and "Display name" of your choice.
- Enter the URL to your Git repository.
artifacthubas the branch to track.
Finally, press the "Add" button. This will bring you back to the "Repositories" page, where you will see your freshly created repository.
Each repository has several information fields. Find the "ID" property of the repository you just created and copy it.
Go back to your Git repository and edit the
artifacthub-repo.yml. Ensure the
repositoryID key found inside of the document has the value you just copied from the
Artifact Hub web page.
The format of the
artifacthub-repo.yml file is defined
Now it's a good time to do some further customizations to this file.
Once you are done with the changes, commit the updated
file and push it. During the next scan, Artifact Hub will find this file and
it will add the
"Verified Publisher" badge
to you Artifact Hub repository.
Keeping Artifact Hub in Sync
Do not forget to update the contents of the
every time you release a new version of your policy.
The contents of the
artifacthub-repo.yml file do not need to be changed.