Skip to content

Publishing Extensions

Publishing an extension is an easy way to:

  • recruit collaborators for a project
  • increase your user base and, along with it, the potential for:
    • contributed bug fixes
    • new use cases
    • feature requests and project funding
  • bring positive attention to your organization
  • share a useful feature or set of configurations with worthy nonprofit and community organizations

While you could simply publish your extension to a web-based code repository like GitHub, publishing through the CiviCRM Extensions Directory makes it easy for others to find and download it. Moreover, CiviCRM extensions which undergo a formal review can even be distributed in-application to CiviCRM sites.

Publishing a CiviCRM extension

CiviCRM's publishing process automates a number of tasks related to maintaining your extensions. Provide some basic information about the extension, and the rest is taken care of for you! Subsequent releases will automatically be detected, published, and submitted for translation.

Prerequisites

  • The extension code is published on CiviCRM's Gitlab or on a public GitHub repository.
  • The extension manifest (info.xml) is in the root of the repository.
  • The extension manifest is valid.
  • Each release of the extension has a git tag using a "semantic version number string such as "1.2.3" (major.minor.patch). The recommended practice is to increment the:
  • major version when you make breaking changes,
  • minor version when you add functionality in a backward compatible manner,
  • patch version when you make backward compatible bug fixes.

You can tag alpha/beta releases, but they will not be listed in the directory. We assume that the objective of alpha/beta releases is for advanced users running a test environment. It would be confusing for regular administrators to see weekly alpha/beta releases of the extension in the CiviCRM extension directory, or to be notified in-app about a new beta upgrade available.

Publishing an extension:

  • Register for an account on civicrm.org if you do not already have one.
  • Login to civicrm.org and create a new extension node. If you see an "Access Denied" message, you'll need to email info@civicrm.org with your user id and request permission to publish extensions, or you can ask in the extensions channel on the CiviCRM chat.
  • Fill out all required fields.
  • Complete the steps in "Publishing an extension release" below.
  • If your extension is hosted on CiviCRM's Gitlab, a new release will be added immediately when the release it tagged. You will receive an email notifying you that the extension was published on civicrm.org or that a problem with the extension manifest (info.xml) prevented publication.

Extensions added to civicrm.org automatically create a Gitlab project on CiviCRM's Gitlab. You can still use a git repository on Github, however using CiviCRM's Gitlab has the advantage of increasing the potential for collaboration with the rest of the community. Further more, new releases are published immediately on civicrm.org, instead of waiting 24 hours. Read more on the CiviCRM blog. If you prefer to use Github, edit your extension page and update the "Git URL" field.

Publishing an extension release:

  • Update the extension manifest and push the changes to your GitHub repository. At minimum you'll need to increment the version number.
  • Create a git "tag" which matches the version in the manifest and push it, e.g.:
git tag -a 1.2.0
git push origin 1.2.0
  • Now to get that release on CiviCRM.org:
  • If your extension is on GitLab (strongly recommended!) you don't need to do anything, an automatic webhook will fire off the instructions to publish the new release on CiviCRM.org for you!
  • If your extension is on GitHub you'll need to wait upto 24 hours for the CiviCRM extension directory to detect the new release and publish the node on CiviCRM.org.

Automatic release publishing disabled

If you have disabled the automatic publishing of new release nodes on CiviCRM.org you will need to manually review and publish your release before it will be publically visible!

  • Once the publishing has triggered you will receive an email notifying you that the release was published on civicrm.org or that a problem with the extension manifest prevented publication.

Notes for CMS-specific plugins or modules

CMS-specific plugins or modules are developed for a single CMS environment (Backdrop, Drupal, Joomla, WordPress), typically using the extension framework of the CMS in question (for example, webform_civicrm is packaged as a Drupal module). Sometimes they assume that CiviCRM runs inside the CMS, and sometimes they communicate with the CiviCRM API remotely.

These plugins or modules can be published on the CiviCRM.org extension directory. This will not provide in-application distribution, but provides better visibility. We recommend publishing them to both the CiviCRM directory and the relevant CMS extension directory (drupal.org, etc), to take advantage of the distribution system of the CMS.

To publish a CMS-specific plugin or module, follow the steps outlined above for publishing an extension. Note that most of the prerequisites do not apply, and that you may choose not to supply a "Git URL." The directory does not track individual releases for CMS-specific plugins or modules.

Automated distribution

The best way to reap the benefits of publishing your extension is to make it as easy as possible for others to install it. With just a few clicks, CiviCRM site administrators can view and install CiviCRM extension releases which meet certain criteria. To be eligible for automated distribution:

  • The extension must be published in the Extensions Directory.
  • One of the extension's maintainers must request an extension review.
  • The extension manifest must flag the release as "stable."
  • The extension manifest must flag the release as compatible with CiviCRM version 4.2 or greater.
  • The release must be CMS-agnostic, and it must install without errors or notices from the Manage Extensions page of a site running a stable release of CiviCRM. Errors installing in any of the supported CMSes are grounds for holding an extension back from automated distribution.
  • The extension must provide the promised functionality. Serious bugs and errors found by a CiviCRM community extension moderator exploring the functionality of the extension are grounds for holding an extension back from automated distribution.

It is strongly recommended that you write unit tests for the extension and include them in the extension's repository. For an example, see the extension org.civicrm.exampletests.

Once an extension release meets these criteria, the extension will be approved for automated distribution by a CiviCRM community extension moderator.

For more information, see the Extension Lifecycle.

Translation

When an extension is approved for automatic distribution, it will automatically be added to Transifex under the civicrm_extensions project so that any strings in the interface (if there are any) may be translated.

This synchronisation task is run nightly. It also generates the translation files, which may be downloaded with the Update Language Files extension or by guessing the URL using the form:

https://download.civicrm.org/civicrm-l10n-extensions/mo/i18nexample/fr_FR/i18nexample.mo