Published on 12 June 2019 by

Fully automating the lifecycle of your Puppet module -- it's the stuff dreams are made of. Okay, maybe not so much for the general public, but if you're a module developer, this is an exciting prospect!

We're pleased to announce a new collection of Forge API endpoints that allow for complete programmatic module management. What does that mean? It's now possible to log in to your Forge account, create an API key, and use that key to publish, delete, or deprecate any of your modules directly through the Forge API.

Let’s get going.

Current publishing options

Taking a step or two back, we know there are a lot of module developers out there using Blacksmith to publish their modules, so you may be wondering how the new endpoints are an improvement. Blacksmith is a great tool that the Puppet community built in part to fill the gaps in the Forge API. However, some of the prior limitations in the API meant that the publishing flow of the Blacksmith implementation is somewhat less than ideal.

For example, since we hadn't yet implemented authentication through API keys, the Blacksmith workflow involves passing a Forge username and password in plain text. This made automated publishing possible, but we’re excited to be able to provide a more standard authentication flow.

Beyond just publishing

Initially we only set out to create a publish endpoint within our v3 namespace for the Forge API. After thinking about the work this would entail and the community needs, we decided it was important to add endpoints for other essential module management tasks as well, namely deletion and deprecation. We ended up adding the following endpoints:

  • POST /v3/releases
  • DELETE /v3/releases/<release-slug>
  • DELETE /v3/modules/<module-slug>
  • PATCH /v3/modules/<module-slug> (used for module deprecation)

With that, it's possible to automate the entire module lifecycle. Here's an outline of what those steps might look like using curl:

To publish a new module release using curl, you can run this command:

$ curl -D- --request 'POST' 'https://forgeapi.puppet.com/v3/releases' \
      -F [email protected] \
      -H 'Authorization: Bearer <REPLACE WITH YOUR API KEY>'

And to mark a module release as deleted:

$ curl -D- --request DELETE \
     'https://forgeapi.puppet.com/v3/releases/nkanderson-testmodule-0.1.0?reason=buggy+release' \
     -H 'Authorization: Bearer <REPLACE WITH YOUR API KEY>'

Deleting the entire module will mark all individual releases as deleted, effectively removing it from the Forge web interface:

$ curl -D- --request DELETE \
     'https://forgeapi.puppet.com/v3/modules/nkanderson-testmodule?reason=buggy+module' \
      -H 'Authorization: Bearer <REPLACE WITH YOUR API KEY>'

To mark a module as deprecated, use the PATCH method. Note that json data is required to specify the deprecate action. Optional parameters include the reason for deprecation and the slug for a replacement module.

$ curl -D- --request PATCH 'https://forgeapi.puppet.com/v3/modules/nkanderson-testmodule' \
     -d '{"action": "deprecate", "params": {"reason": "No longer maintained", "replacement_slug": "puppetlabs-mysql"} }' \
     -H 'Content-Type: application/json' -H 'Authorization: Bearer <REPLACE WITH YOUR API KEY>'

Bonus: Updated docs!

Once we got into the documentation phase for these new endpoints, we realized our Forge API docs could use a little love. So another improvement we made along the way was to update our docs framework. Beyond just a fresh coat of paint, the new docs are clearer and easier to navigate, with added descriptions for a handful of parameters that hadn’t previously surfaced from implementation to the docs.

Check out these new Puppet Forge API docs!

New Forge API docs -- check them out!

Want to try it out? Log in to your Forge account, navigate to your user profile page (hint: click your name in the upper right), and on that page you'll see an option to create a new key. Once you've created a key, you're all set to hit the ground running with automating your module management.

Nik Anderson is a software engineer at Puppet.

Learn more

Share via:
Posted in:
Tagged:
The content of this field is kept private and will not be shown publicly.

Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.