(Quick Reference)

2 Configuration - Reference Documentation

Authors: Peter Ledbrook

Version: 3.0.0

2 Configuration

You can use the publish-plugin command to release plugins to the Grails Central Plugin Repository without any configuration whatsoever, but if you want to manage your own plugin repository and/or portal you will have to master the available configuration settings. The same goes if you want to deploy artifacts to a custom Maven-compatible repository. But don't worry: it's all very straightforward.

All the configuration options described in the next section can either go into your project's BuildConfig.groovy file or your personal ~/.grails/settings.groovy. The latter is particular useful for storing credentials since the file is typically not stored in a shared source repository, thus making it easy to keep that information confidential.

Let's start by looking at how you can configure a Maven-compatible repository, since this is the most common scenario.

2.1 Repositories

With tools like Nexus and Artifactory, it's pretty easy to set up a Maven-compatible repository these days. Fortunately, it's equally easy to publish Grails plugins and applications to such repositories.

Let's say you have a repository running on your local machine and you want to deploy a plugin to it. Your first step should be to assign the repository a unique ID, such as 'myRepo'. Next, you tell Grails where to find the repository by adding an entry to BuildConfig.groovy specifying its URL:

grails.project.repos.myRepo.url = "http://localhost:8081/repos"

The general form of the above configuration option is grails.project.repos.<repoId>.url.

You can not use a repository ID of 'grailsCentral'. That is because it is reserved for the Grails Central Plugin Repository. The good news is that you can configure the username and password for 'grailsCentral' via the options described below.

You can now deploy artifacts to the repository by passing a --repository=myRepo argument to either the publish-plugin or maven-deploy commands. Since you often deploy a plugin or application to the same repository again and again, typing that argument gets a bit laborious, so you can also specify the name of a default repository to deploy to:

grails.project.repos.default = "myRepo"

The above configuration option means that a project will be deployed to "myRepo" unless an explicit --repository argument is provided on the command line. You can also pass a value of "grailsCentral" for the command line option or the 'default' config setting to indicate you want to publish to the Grails Central Plugin Repository. Note that the command line option always takes precedence over other settings.

Things become slightly more verbose if you want to provide extra details about the repository. What about user credentials for example? Here's a comprehensive configuration:

grails.project.repos.myRepo.url = "http://localhost:8081/repos"
grails.project.repos.myRepo.type = "maven"
grails.project.repos.myRepo.username = "admin"
grails.project.repos.myRepo.password = "password"
grails.project.repos.myRepo.portal = "grailsCentral"

As you can see, even a complete explicit configuration is pretty short. So what do the various entries mean?

  • url - the URL to use when connecting to the remote repository. Typically this is HTTP-based, but "svn+ssh" is not uncommon for old-style Subversion plugin repositories.
  • type - can be either "maven" or "svn", but the former is the default value so it's rare to explicitly declare a value of "maven" for this option.
  • username - the username for connecting to the repository.
  • password - the password for connecting to the repository.
  • portal - the ID of the plugin portal to notify when publishing a plugin to this repository. Only affects the publish-plugin command.

These settings are common to both Maven-compatible and Subversion repositories - it's only the values that typically differ between them. It's also worth bearing in mind that Subversion repositories can only be used for plugins.

The last option, portal, raises the question of how to declare plugin portals. What exactly is meant by a portal ID? The answer lies with portal configuration.

2.2 Plugin portals

When a Grails plugin is published to a repository, a plugin portal can optionally be notified of the release. For example, when you publish a plugin to the Grails Central Plugin Repository, the command will automatically notify the main plugin portal on the grails.org website. That means people can see the details of the new release almost immediately.

Like repositories, portals have very few configuration options:

grails.project.portal.<portalId>.url = "http://beta.grails.org/plugin/" 
grails.project.portal.<portalId>.username = "joe" 
grails.project.portal.<portalId>.password = "ht56jU&B"
  • url - the URL of the plugin portal.
  • username - the username to use when notifying the portal.
  • password - the password to use.

One thing to bear in mind: as with repositories, the ID 'grailsCentral' is reserved, this time for the main plugin portal on grails.org. Of course, you can still configure a username and password for this portal using the above settings.

2.3 Source control management

By default, source control management is enabled for the publish-plugin command. This means that the command ensures that the latest changes are committed and tagged before a plugin is published. If you don't want the command to do this, then you can disable it via the --noScm command line option, but that gets tedious if you use it every time you run the command.

An alternative approach is to use a configuration setting to disable source control management for the project (or all projects if you put it into ~/.grails/settings.groovy):

grails.release.scm.enabled = false

Once the above setting is in place, publish-plugin will no longer attempt to commit and tag source changes. Of course, if you do this you lose the benefit of the plugin keeping the source and the published plugins reliably in sync.