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. With just a few clicks, CiviCRM site administrators can view and install CiviCRM extension releases.

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 go to Create content > Add an extension. If you do not see the menu option, or if you see an "Access Denied" message, please make a request 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 make two changes in order for the release to be published as the latest release: increment the version number; and update the release date.
  • 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.

By default, any extension from the CiviCRM extension directory can be installed directly from the CiviCRM administrative interface (Administer > System Settings > Extensions). There are two conditions: the extension must have a release compatible with that version of CiviCRM, and the extension must have a stable version released in the past two years.

Extensions are sorted using two criteria: recommended extensions are listed first, then they are sorted by the number of active installs.

To become a recommended extension, the extension must meet certain criteria and pass a review. 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