How to publish your charm on Charmhub

doc
1

See also:

This document shows how to publish your charm to the official repository of charms, Charmhub.

Contents:

  1. Log in to Charmhub
  2. Register your charm’s name
  3. Upload the charm
  4. Release the charm
  5. Promote a charm revision to a lower risk level of the same track

Log in to Charmhub

To log into Charmhub, run charmcraft login:

$ charmcraft login
Opening an authorization web page in your browser.
If it does not open, please open this URL:
...

See more: charmcraft login

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.

Register your charm’s name

To register your charm’s name to your account, choose a suitable name and then run the charmcraft register command followed by your desired charm name:

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

You only need to register the name if you haven’t already registered it before. You can check which names you have already registered by running charmcraft names. See more: charmcraft names.

See more: charmcraft register, Charm naming guidelines

Upload the charm

To upload the charm, use the charmcraft upload command followed by the your charm’s filepath.

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

See more: charmcraft upload

If your metadata.yaml lists any resources: Those did not get packed with charmcraft pack, so they didn’t get uploaded with charmcraft upload <charm> either. Make sure to upload them as well! See more: How to upload a resource to Charmhub.

Every time a new binary is uploaded for a charm, a new revision is created on Charmhub. We can verify its current status easily by running charmcraft revisions <charm-name>. See more: charmcraft revisions.

Release the charm

See also: charmcraft release, charmcraft status

Finally, release your charm into a channel so it can become available for downloading:

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

Uploaded charms are not automatically released and made available for download. To consume a charm, first release it into a channel (any channel). Then Charmhub will display the charm’s information at charmhub.io/<charm-name>. (The default information displayed is obtained from the most stable channel.)

Just in case, also check your charm’s status:

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

Promote a charm revision to a lower risk level of the same track

See also: Promotion

There is currently no easy way to accomplish this with Charmcraft (though there is a feature request in progress: link). At present we recommend you use the GitHub promote-charm action.

See more: GitHub | canonical/charming-actions/promote-charm


Contributors: @facundo , @jnsgruk , @lucabello , @pmatulis, @ppasotti, @sed-i , @tmihoc , @toto

2

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>?
3

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
4

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
5
6

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.

7

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).

8

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.

9

Hi,

This document mentions “tracks”, and “versions” for a charm. Further charmcraft help release also mentions “branch”. However it is not clear what is the charmcraft command line syntax (with some examples) on how does one release a charm for a specific “version”, “track” and “branch” in addition to “risk”. Some guidelines regarding use of these features may also be useful in the context of this document.

regards

10

Had exactly the same thought, so I added a note to that effect in the creating-icons-for-charms article.