With the general availability of GitHub Packages container registry, or GHCR for short, an easily accessible Docker registry made its way into the same platform many developers use for version control today. This was great news for containers and simplifying infrastructure, just like Actions greatly simplified workflows on GitHub.
But wait, there's more!
GitHub container registry also supports the Open Container Initiative (OCI) specification, which doesn't limit "containers" to just Docker containers, and it supports public anonymous downloads! This makes GHCR a perfect target for hosting OCI-compliant artifacts, like wasmCloud actors and capability providers. Today, we're going to walk through evolving use cases for getting more power out of this feature of GitHub and how it can simplify your wasmCloud development beyond running on your local machine.
Today we'll be using a couple of tools for this tutorial:
- A Rust toolchain to build actors
- Make sure to add wasm32 as a target with
rustup target add wasm32-unknown-unknown
- Make sure to add wasm32 as a target with
- wash, the wasmCloud shell, at least
To start, let's go ahead and generate a new wasmCloud actor project from the
hello project template. This is our "hello world" actor.
wash new actor hello
Once the project is generated,
cd hello into the project. There, you can run
cargo build --release build your actor module. The last step before we can push it to GitHub is to sign the actor with embedded claims. The following command will sign your actor and allow it to access the HTTPServer capability:
wash claims sign target/wasm32-unknown-unknown/release/hello.wasm --http_server --name Hello
By default this will place the actor under the same directory with a
_s suffix, and you can verify this worked properly by running:
wash claims inspect target/wasm32-unknown-unknown/release/hello_s.wasm
Your output should be something like this, just with different
Hello - Module Account ABYFZKXEHQWJIMBKVAVG3Y5LGEBT3MQXRYVTQBF7RVHUIG62LUK3N5EQ Module MAMP52XKSBHNDMWK4OR4BZVBDQNNZQ5FXDXUAX7KIT7KNOKK2N3CCLZ2 Expires never Can Be Used immediately Version None (0) Call Alias (Not set) Capabilities HTTP Server Tags None
Now that we've built and signed your actor, let's push it to GitHub! To do this, you'll need a personal access token with the
write:packages capability. Refer to the link for instructions on how to create this personal access token, and feel free to tweak the other parameters to your liking.
Once created, copy this token and store it in a safe place before moving back to your terminal.
Now, time to push! We'll use
wash here along with some environment variables.
WASH_REG_USER should be set to your GitHub username, and
WASH_REG_PASSWORD should be set to your GitHub personal access token that you created before, starting with
export WASH_REG_USER=<your_github_username> export WASH_REG_PASSWORD=<your_gitub_personal_access_token> wash reg push ghcr.io/$WASH_REG_USER/hello:0.1.0 target/wasm32-unknown-unknown/release/hello_s.wasm
You should see output like the following:
wash reg push ghcr.io/$WASH_REG_USER/hello:0.1.0 target/wasm32-unknown-unknown/release/hello_s.wasm 🚿 Successfully validated and pushed to ghcr.io/brooksmtownsend/hello:0.1.0
Now, you can navigate to your GitHub profile and access the
Packages tab to see your
By default, our actor package is private so that it cannot be downloaded anonymously. Any wasmCloud host can be configured with a username and password for registry authentication, and in this case you can supply your GitHub username and personal access token to authenticate and download your actor. However, this step can be missed easily, so let's make this actor package public so you can start it anywhere. Click on your package, then on the "⚙️ Package Settings" sidebar. From there, scroll to the bottom and "Change visibility" to public.
Now you can download and run that actor on any wasmCloud host, which can be on Mac, Linux, Windows, or even in a browser tab! You can test connectivity at any time by running:
wash claims inspect ghcr.io/<your_github_username>/hello:0.1.0
Now that we have a Package set up for our actor, the next step is to connect it to a repository. Once we do that we can take advantage of the built-in Actions that are provided with an actor project to automatically build, test, and release actors.
First step is to create a GitHub repository. For simplicity, let's call it
hello to match the actor name.
Once that's created, we need to associate our local actor project with the GitHub repository.
cd hello into your actor project if you haven't already, and then:
git add . git commit -m "initial commit" git branch -M main # If you named your repository something else, simply replace the URL below git remote add origin https://github.com/<your_github_name>/hello.git git push -u origin main
For every commit after this one, and every pull request into
main , your actor will be automatically built, checked for formatting, lints, and tested once you add unit tests and uncomment the
cargo test step in
.github/workflows/release.yml action, we need to configure three repository secrets to properly sign and release your actor. The good news is, we already have all of these secrets, we just need to plop them in GitHub!
Under your repository settings, head to the
Secrets dropdown and click
Actions . Here we can configure the following secrets for use in this repository.
|WASH_ISSUER_KEY||Can be found under
|WASH_SUBJECT_KEY||Can be found under
|WASMCLOUD_PAT||Your personal access token that you previously used for
Once these three secrets are configured, let's cut our first release of the
hello actor. Head back to your command line and create a tag for
v0.1.0 and push it to
git tag -a v0.1.0 -m "initial release for hello actor" git push -u origin v0.1.0
This will automatically kick off the release action, which includes building and testing the actor just like the build action, and after a few minutes you'll see a new GitHub release created with the OCI URL for the actor and claims information, as well as the
hello package associated with this repo.
Today we walked through the setup process to configure a GitHub repository to automatically build, test, and release wasmCloud actors to GitHub Packages. You can continue to add to these base workflow templates to include your own custom checks as well.
Now that your
hello actor is published to a public OCI registry, you can follow our run actor tutorial with the OCI reference instead of uploading a local file. If you're new to wasmCloud, check out our documentation for helpful information about actors, our security model, and more. Feedback on this process is welcome and encouraged on our project-templates repo; and to stay involved you can join our slack.