Publishing

Once you have built your charm, you should publish it to Charmhub. This section will guide you through the process.

Build your charm

Before your charm can be published, it needs to be built. The build process will fetch any dependencies you’ve specified in your requirements.txt and package them up with your charm code in a .charm package:

$ charmcraft pack
Done, charm left in 'hello-operator.charm'

A .charm file is just a zip file, and can be unzipped and examined as such.

Register a name

Before you can interact with Charmhub using charmcraft you’ll need to login:

$ charmcraft login
Opening an authorization web page in your browser; if it does not open, please open this URL: https://api.staging.jujucharms.com/identity/login?did=<id>
Login successful.

Your charmcraft session will expire automatically, but you’ll be prompted to re-authenticate automatically next time you try to access a feature that requires interaction with Charmhub

If you’re publishing your charm for the first time, you’ll need to register the name to your account:

$ charmcraft register my-awesome-charm
Congrats! You are now the publisher of 'my-awesome-charm'

You can check the charm names registered to your account at any time:

$ charmcraft names
Name                  Visibility    Status
# ...
my-awesome-charm      public        registered
# ...

Upload and Release

The charm is now ready to be uploaded, which is achieved by invoking charmcraft upload and passing the filename of the built charm:

charmcraft upload my-awesome-charm.charm
Revision 1 of my-awesome-charm created

Every time a new binary is uploaded for a charm, a new revision is created on Charmhub. We can verify its current status easily:

$ charmcraft revisions my-awesome-charm
Revision    Version    Created at    Status
1           0.1        2020-07-23    approved

Uploaded charms are not automatically released and made available for download. Once a charm is uploaded, it must be released into a channel before it can be consumed:

$ charmcraft release my-awesome-charm --revision=1 --channel=beta
Revision 1 of charm 'my-awesome-charm' released to beta

Note that Charmhub uses information from the stable channel to populate the information on a charm’s homepage by default.

Finally, we can see the overall status:

$ charmcraft status my-awesome-charm
Track    Channel    Version    Revision
latest   stable     -          -
         candidate  -          -
         beta       0.1        1
         edge       ↑          ↑

If your charm is designed to work on Kubernetes, or otherwise requires the use of Charm Resources, there are additional steps required to upload the resources and attach them to a release. Read more in the Publishing Resources section.

We need more information about the permission model in charmhub, for example:

  • How are teams created? Are they tied to Launchpad?
  • How to list/grant/revoke permissions?
  • How to upload a version of a charm under my own namespace like I would do with charm push <charm-name> cs:~alejdg/<charm-name>?

Hi Alexandre,

The final details of all this is still be worked out and there are a few missing bits currently, or things that need manual intervention from the charmhub team. Some of this is by design (e.g. some charm names have been reserved and need discussion if you want it assigned to you), but the tools could do with updates to make it more obvious when this is the case.

I can talk you through more of the detail next week, but I see you’ve also filed a bunch of issues against charmhub.io and charmcraft already.

Thanks, Tom

1 Like

Hey, looks like @mthaddon mostly got you covered here. One other point to note is that there are no user namespaces on Charmhub.

1 Like

Hi and thanks for this useful doc! This advertises publishing to the beta channel instead of stable, which is good but led to an unexpected behavior in my case: when editing metadata.yaml (e.g. changing the charm’s summary) and re-publishing, the changes aren’t reflected on the charm store. I clarified with people from the charmhub: once a charm has been published once, new changes will be reflected only when publishing to the stable channel, even if nothing has ever been published to that channel yet.

I’m wondering if there should be a warning here, or if this should be improved on the charmhub? Maybe the charmhub should reflect changes when publishing to the “currently most stable” channel, not only stable.

Hi Jon,

One thing I believe is missing from the publishing doc is how to add an icon to your charm. This is somewhat described at Creating icons for charms ; I think we should link to that post and be explicit about the filename requirements (i.e. an icon.svg file in the charm root - I believe).

Hi, thanks! Have put a note into the docs.

Thanks, I’ve added a section under charm anatomy to include a icon.svg and a link to that article.