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.
Create a 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 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 may not 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
directory and is known to the Forge as "puppetlabs-mysql".
In your module's
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
metadata.json file already
contains the correct long name for the module. Otherwise, edit your module's
metadata with the correct long name.
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 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 will be 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.
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.
metadata.jsonfile contains the correct information.
metadata.jsonmust be UTF-8 encoded. If you used 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 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
files in your module.
If you are building your module with
PDK, your module package
will contain 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
If you are building your
module with the
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
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.
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
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
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
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.
.tar.gz package with the
in the module's
subdirectory. For complete details about this task,
see the PDK topic about
Change into the
module directory by running
Build the package
- 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.
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 Puppet 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 will load the new release page for your module. If there were any errors on your upload, they will 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.
- Enable Travis CI for the module repository.
- Generate a Travis-encrypted Forge password string. For instructions, see the Travis CI encryption keys docs.
.travis.ymlfile 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
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.
- Update the version number in the module's
Deprecate a module on the Forge
To let your module users know that you are no longer maintaining your module and that they should stop using it, deprecate your module on the Forge.
The full name of the module to be deprecated, such as
The reason for the deprecation. The reason will be publicly displayed on the Forge.
A recommended alternative module or workaround.
Delete a module release from the Forge
To delete a release of your module, use the Forge
web interface. A deleted release is still downloadable via the Forge page or
module command if a user requests the module by
- In your web browser, navigate to the Puppet Forge and log in.
- Click Your Modules.
- Go to the page of the module release you want to delete.
- Click Select another release, choose the release you want from the drop-down list, and click Delete.
confirmation page that loads, supply a reason for
the deletion and submit.
The reason you give for deleting your module will be visible to Forge users.
- Click Yes, delete it.
On your module page, you will see a banner confirmation of the deletion.