- Naming your module
- Create a Forge account
- Preparing your module for publishing
- Build your module
- Upload a module to the Forge
- Publish to the Forge automatically with Travis CI
- Deprecate a module on the Forge
- Delete a module release from the Forge
- Finding and downloading deleted 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:
- Create a Puppet Forge account, if you don’t already have one.
- Prepare your module for packaging.
- Add module metadata in the
- Build an uploadable tarball of your module.
- Upload your module using the Puppet Forge’s web interface.
- Module fundamentals: How to write and use your own Puppet modules.
- Installing modules: How to install pre-built modules from the Puppet Forge.
- Using plugins: How to arrange plugins (such as custom facts and custom resource types) in modules and sync them to agent nodes.
- Documenting modules: How to write good documentation for your modules.
- Puppet Development Kit: A package of development and testing tools to help you create great modules.
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”.
To upload to the Forge, use the module long name. This 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 known to the Forge as “puppetlabs-mysql”. Use this long name in your module’s
metadata.json file. This helps disambiguate modules that might have common short names, such as “mysql” or “apache.”
However, your module directory on disk must use the short name, without the username prefix. Module directory names cannot contain dashes or periods; only letters, numbers, and underscores. As long as you have the correct long name in your
metadata.json file, the
puppet module build command uses the correct names in the correct places.
Note: Although the Forge expects to receive modules named
username-module, its web interface presents them as
username/module. Always use the
username-modulestyle in your metadata files and when issuing commands.
Create a Forge account
To publish your modules to the Forge, you need to create a Forge account.
In your web browser, navigate to the Forge website and click Sign Up.
Fill in your details. The username you pick will be the first part of your module long name (such as “bobcat/apache”).
After you sign up, you will receive a verification email. After you verify your email, you can publish modules to the Forge.
Preparing your module for publishing
Before you build your module package for publishing, you’ll need to make sure it’s properly prepared.
To do this, you’ll exclude unnecessary files from your package or repository, remove or ignore any symlinks your module contains, and make sure your
metadata.json contains the correct information.
Note: In order to successfully publish your module to the Puppet Forge and ensure that everything is rendered correctly, your README, license file, changelog, and metadata.json must be UTF-8 encoded. If you used the Puppet Development Kit (or the deprecated
puppet module generatecommand) 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 a
.gitignore or a
.pmtignore file. This is useful for excluding files that are not needed to run the module, such as files generated by spec tests. The ignore file must be in the root directory.
import/ /spec/fixtures/ .tmp *.lock *.local .rbenv-gemsets .ruby-version build/ docs/ tests/ log/ junit/ tmp/
.pmtignore file excludes files during
puppet module build only. For example, you might want spec tests in your source control but not in your module package, so you would list them in
.pmtignore. To prevent files, such as those in temporary directories, from ever being checked into Git, use
If you have both a
.pmtignore and a
.gitignore file, the
puppet module command uses the
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 will receive the following error:
Warning: Symlinks in modules are unsupported. Please investigate symlink manifests/foo.pp->manifests/init.pp. Error: Found symlinks. Symlinks in modules are not allowed, please remove them. Error: Try 'puppet help module build' for usage
Adding module metadata in metadata.json
To publish your module on the Forge, it must contain required metadata in a
If you generated your module using the Puppet Development Kit or the deprecated
puppet module generate command, you’ll already have a
metadata.json file. Check it and make any necessary edits.
If you assembled your module manually, you must make sure that you have a
metadata.json file in your module’s main directory. For details on writing or editing the
metadata.json file, see the related topic about module metadata.
If you maintain older modules, you might find the metadata stored in a Modulefile. Move any metadata contained in the Modulefile to the
metadata.json. Modulefiles were deprecated in Puppet 3 and removed in Puppet 4. They are now treated like any other text file in the root directory of the module.
Build your module
To upload your module to the Forge, you first must build the module package.
From the command line, run
puppet module build <MODULE DIRECTORY>. This command generates a
.tar.gzpackage and saves it in the module’s
# puppet module build /etc/puppetlabs/puppet/modules/mymodule Building /etc/puppetlabs/puppet/modules/mymodule for release /etc/puppetlabs/puppet/modules/mymodule/pkg/examplecorp-mymodule-0.0.1.tar.gz
Upload a module to the Forge
To publish a new module release to the Forge, upload the module tarball to the Forge using the web interface.
Your module package should 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.
After a successful upload, your browser should load the new release page of your module, with any errors popping up on the same screen. Your module’s README, Changelog,and License files are displayed on your module’s Forge page.
Publish to the Forge automatically with Travis CI
You can automatically publish new versions of your module to the Forge using Travis CI.
First, set up Travis CI for automatic publishing.
- Enable Travis CI for the module repository.
- Generate a Travis-encrypted Forge password string. For instructions, see the Travis CI encryption keys docs.
- Create a
.travis.ymlfile in the module’s repository base. This file should have 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 your version, tag your repo, and push your commit.
- Update the version number in the module’s
metadata.jsonfile and commit the change to the module repository.
- Tag the module repo with the desired version number. For more information about how to do this, see Git docs on basic tagging.
- Push the commit and tag to your Git repository.
Travis CI will build and publish the module.
Deprecate a module on the Forge
To let your module users know that you are no longer maintaining your module and that they should cease using it, deprecate your module on the Forge.
File a FORGE ticket in our JIRA project. The ticket should include:
- The full name of the module to be deprecated, such as
- Optionally, the reason for the deprecation. The reason will be publicly displayed on the Forge.
- Optionally, a recommended alternative module or workaround.
- The full name of the module to be deprecated, such as
Delete a module release from the Forge
If you want to delete a release of your module, you can do so from the Forge’s web interface.
A deleted release is still downloadable via the Forge page or
puppet module command if a user requests the module by specific version. You cannot delete a released version and upload a new version of the same release.
In your web browser, navigate to the Puppet Forge and log in.
Click Your Modules.
Go to the module page of the module release you want to delete.
Locate Select another release, choose the release you want from the drop-down list, and click Delete.
A confirmation page will load, and you must supply a reason for the deletion. Note: Your reason will be visible to Forge users.
Click Yes, delete it.
On your module page, you will see a banner confirmation of the deletion.
Finding and downloading deleted modules
You can still search for and download a specific release of a module on the Forge, even if the release has been deleted.
Normally, deleted modules do not appear in Forge search results. To include deleted modules in your search, check Include deleted modules in the Forge search filter panel.
To download a deleted release of a specific module, select the release from the Select another release drop-down list on the module page. The release is marked as deleted but is still an option in the menu.
If you select the deleted release, a warning banner appears on the page with the reason for deletion. To download the deleted release anyway, click Download or install it with the
puppet module install command.