Publishing modules

To share your module with other Puppet users, get contributions to your modules, and maintain your module releases, publish your module on the Puppet Forge. The Forge is a community repository of modules, written and contributed by open source Puppet and Puppet Enterprise users.

To publish your module, you'll:

Create a Forge account, if you don't already have one.
Prepare your module for packaging.
Add module metadata in the metadata.json file.
Build an uploadable tarball of your module.
Upload your module using the Forge web interface.

Naming your module

Your module has two names: a short name, like "mysql", and a long name that includes your Forge username, like "puppetlabs-mysql". When you upload your module to the Forge, use the module's long name.

Your module's short name is the same as that module's directory on your disk. This name must consist of letters, numbers, and underscores only; it can't contain dashes or periods.

The long name is composed of your Forge username and the short name of your module. For example, the "puppetlabs" user maintains a "mysql" module, which is located in a ./modules/mysql directory and is known to the Forge as "puppetlabs-mysql".

In your module's metadata.json file, always use the long name of your module. This helps disambiguate modules that might have common short names, such as "mysql" or "apache." If you created your module with Puppet Development Kit (PDK), and you provided your Forge username to PDK, the metadata.json file already contains the correct long name for the module. Otherwise, edit your module's metadata with the correct long name.

Tip: Although the Forge expects to receive modules named username-module, its web interface presents them as username/module. Always use the username-module style in your metadata files and when issuing commands.

Create a Forge account

To publish your modules to the Forge, you must first create a Forge account.

In your web browser, navigate to the Forge website and click Sign Up.
Fill in the fields on the sign-up form. The username you pick becomes part of your module long name, such as "bobcat-apache".
Check your email for a verification email from the Forge, and then follow the instructions in the email to verify your email address.

Results

After you have verified your email address, you can publish modules to the Forge.

Prepare your module for publishing

Before you build your module package for publishing, make sure it's ready to be packaged.

Exclude unnecessary files from your package, remove or ignore any symlinks your module contains, and make sure your metadata.json file contains the correct information.

Tip: To publish your module to the Forge, your README, license file, changelog, and metadata.json must be UTF-8 encoded. If you used Puppet Development Kit (or the deprecated puppet module generate command) to create your module, these files are already UTF-8 encoded.

Excluding files from the package

To exclude certain files from your module build, include them in either an ignore file. Ignore files are useful for excluding files that are not needed to run the module, such as temporary files or files generated by spec tests. The ignore file must be in the root directory. You can use .pdkignore, .gitignore, or.pmtignore files in your module.

If you are building your module with PDK, your module package contains a .pdkignore file that already includes a list of commonly ignored files. To add or remove files to this list, define them in the module's .sync.yml file. For more information about customizing your module's configuration with .sync.yml, see the PDK documentation.

If you are building your module with the puppet module build command, create a .pmtignore file and in it, list the files you want to exclude from the module package.

To prevent files, such as those in temporary directories, from ever being checked into your module's Git repo, list the files in a .gitignore file.

For example, a typical ignore file might look like this:

import/
/spec/fixtures/
.tmp
*.lock
*.local
.rbenv-gemsets
.ruby-version
build/
docs/
tests/
log/
junit/
tmp/

Removing symlinks from your module

Symlinks in modules are unsupported. If your module contains symlinks, either remove them or ignore them before you build your module.

If you try to build a module package that contains symlinks, you receive the following error:

Warning: Symlinks in modules are unsupported. Please investigate symlink manifests/my-module.pp->manifests/init.pp.
Error: Found symlinks. Symlinks in modules are not allowed, please remove them.
Error: Try 'puppet help module build' for usage

Verifying metadata

To publish your module on the Forge, it must contain required metadata in a metadata.json file. If you created your module with PDK or the deprecated puppet module generate command, you'll already have a metadata.json file. Open the file in any text editor, and make any necessary edits. For details on writing or editing the metadata.json file, see the related topic about module metadata.

Build a module package

To upload your module to the Forge, first build an uploadable module package with Puppet Development Kit.

PDK builds a .tar.gz package with the naming convention <USERNAME>-<MODULE_SHORT_NAME>-<VERSION>.tar.gz. in the module's pkg/ subdirectory. For complete details about this task, see the PDK topic about building module packages.

Change into the module directory by running cd <MODULE_DIRECTORY>
Build the package by running pdk build
Answer the question prompts as needed. You can use default answers to optional questions by pressing Enter at the prompt.
At the confirmation prompt, confirm or cancel package creation.

Results

Upload a module to the Forge

To publish a new module release to the Forge, upload the module tarball using the web interface.

The module package must be a compiled tar.gz package of 10MB or less.

In your web browser, navigate to the Forge and log in.
Click Publish in the upper right hand corner of the screen.
On the upload page, click Choose File and use the file browser to locate and select the release tarball. Then click Upload Release.

Results

After a successful upload, your browser loads the new release page for your module. If there were any errors on your upload, they appear on the same screen. Your module's README, Changelog, and License files are displayed on your module's Forge page.

Publish modules to the Forge with Travis CI

You can automatically publish new versions of your module to the Forge using Travis CI.

If this is your first time using Travis CI for automatic publishing, you must first enable Travis CI to publish to the Forge.
1. Enable Travis CI for the module repository.
2. Generate a Travis-encrypted Forge password string. For instructions, see the Travis CI encryption keys docs.
3. Create a .travis.yml file in the module's repository base. Include a deployment section that includes your Forge username and the encrypted Forge password, such as:
```
deploy:
  provider: puppetforge
  user: <FORGE_USER>
  password:
    secure: "<ENCRYPTED_FORGE_PASSWORD>"
  on:
    tags: true
    # all_branches is required to use tags
    all_branches: true
```
To publish to the Forge with Travis CI, update, tag, and push your repository.
1. Update the version number in the module's metadata.json file and commit the change to the module repository.
2. Tag the module repo with the desired version number. For more information about how to do this, see Git docs on basic tagging.
3. Push the commit and tag to your Git repository. Travis CI builds and publish the module.

Publish modules to the Forge with Github Actions and Puppet Development Kit

You can also manually publish new versions of your module to the Forge using Puppet Development Kit, or automate publishing with PDK using Github Actions.

When creating a Github Action to publish to the Forge, ensure that you have access to the Forge API and have your API token on hand.

Set up your Github Action to build a release of your module when triggered and publish it using the PDK release publish command.

Example:


# This is a generic workflow for releasing a Puppet module.
# It requires that the caller sets `secrets: inherit` to ensure
# that secrets are visible from steps in this workflow.
name: "Module Release"

on:
  workflow_call:

jobs:
  release:
    name: "Release"
    runs-on: "ubuntu-latest"
    if: github.repository_owner == 'puppetlabs'

    steps:

      - name: "Checkout"
        uses: "actions/checkout@v4"
        with:
          ref: "${{ github.ref }}"
          clean: true
          fetch-depth: 0

      - name: "Get version"
        id: "get_version"
        run: |
          echo "version=$(jq --raw-output .version metadata.json)" >> $GITHUB_OUTPUT

      - name: "PDK build"
        uses: "docker://puppet/pdk:3.0.0.0"
        with:
          args: "build"

      - name: "Generate release notes"
        run: |
          export GH_HOST=github.com
          gh extension install chelnak/gh-changelog
          gh changelog get --latest > OUTPUT.md
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: "Create release"
        run: |
          gh release create v${{ steps.get_version.outputs.version }} --title v${{ steps.get_version.outputs.version }} -F OUTPUT.md
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: "Publish module"
        uses: "docker://puppet/pdk:3.0.0.0"
        with:
          args: 'release publish --forge-token ${{ secrets.FORGE_API_KEY }} --force'

For more information on Github Actions, visit the Github Actions documentation.
For more information on the PDK release command, visit PDK release command.

Deprecate a module on the Forge

To let your module users know that you are no longer maintaining your module, deprecate your module on the Forge.

File a ticket in the FORGE project on the Puppet JIRA site. The ticket must include:

The full name of the module to be deprecated, such as puppetlabs-apache.
The reason for the deprecation. The reason is publicly displayed on the Forge.
A recommended alternative module or workaround.

Results

Using the Forge API

Use the Forge API to create, delete, and understand your modules.

Create a module release

Use the /v3/releases endpoint in the Forge API to create and publish a new module or a release of an existing module.

Download a module release

Use the /v3/files/{filename} endpoint in the Forge API to download the tarball for an existing module.

Fetch information about a module release

Use the /v3/releases/{release_slug} endpoint in the Forge API to fetch information about your module, identified by the module's slug value.

Delete a module release

Use the /v3/releases/{release_slug} endpoint in the Forge API to soft delete a release of your module, identified by the module's slug value. A deleted release is still downloadable from the /v3/files endpoint, but not available in Puppet Forge.

More information about the Forge API

For more detailed information about the Forge API, including parameters, responses, and example code, see the Forge API documentation.

Was this page helpful?

We’re sorry to hear that!
Please tell us why so we can help. Enter your feedback and email. This form is sent to the Puppet docs team. We ask for your email as we might contact you regarding your feedback. If you need help with the product itself, visit Puppet Support or ask in Puppet Community on Slack. Feedback:

Email Address:

To learn about how Puppet uses your personal information, visit our privacy policy.

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.