Git repositories

As of version 3.2 MAINTENANCE 03, a new endpoint is available to export/import modules using Git over HTTP(S).

This feature relies on the Eclipse JGit library.

Warning: In production this Git endpoint's URL should be restricted only to allowed origins e.g. using URL filtering on request's origin IP address or similar approaches.

Configuration

The Git repositories are stored on the server file system.

Due to the way the JGit library is designed, the base folder in which these repositories will be located must be passed to the application server as a system property.

This can be done either:

by passing a JVM argument -Dgit.basedir=<path> when starting the application server
by setting it in the application.properties file of your application

Then you also need to set the USE_GIT system parameter to yes.

Export

To export the MyModule module as a Git repository the first thing to do is to create or update the module's repository using the dedicated action on the Module object:

Commit module to Git repository

Then you can clone the module's repository by:

git clone http(s)://<host name>[/<app context root>]/git/<module name>

The credentials you have to use in this case are the same as the one you can use for the I/O interface.

Import

Any git push [origin] on the cloned module's repository triggers a module import (e.g. after having made some local changes or to upgrade another instance by pushing on another remote).

Import from an origin remote

It is possible to configure a module that is linked to an external Git repository by adding following settings to your module:

E.g. from another instance's module repository:

{
  "type": "git",
  "origin": {
    "uri": "http(s)://<instance host name>[/<instance app context root>]/git/<module name>",
    "username": "<I/O user's login>",
    "password": "<I/O user's password>"
  }
}

Any call to the Import module action will then result in either a clone or a pull on the configured remote Git repository.

Typical use case is to link a "slave" instance to a "master" instance. In such a case there are 2 possible ways to export/import a module from the "master" to the "slave" instance:

Directly use the Import module action from the "slave" instance (that will be pulling last commit(s) from the "master" instance)

Use a clone of the "master" instance Git repository configured with an additional remote that points to the "slave" instance. Then git pull will pull from the "master" instance and git push <remote name> will push to the "slave" instance.

E.g. from a public GitHub repository:

{
  "type": "git",
  "origin": {
    "uri": "https://github.com/<profile>/<repository>.git"
  }
}

Note: if you plan to push on this public GitHub repository you must add a username and password or a SSH URI with configured SSH public/private keys.

Advanced

The Git repositories created/cloned by Simplicité:

Are non bare repositories, the local worktree is needed by the export/import processes
Have the following configuration set by default in .git/config file to allow read-write access over HTTP(S):

[http]
        uploadpack = true
        receivepack = true

If you manually create/clone repositories used by Simplicité (which is not supposed to be done except for very specific needs) make sure to create/clone non bare repositories and make sure to have these two options activated (which is not the case by default).

Branch

You can specify the branch to use in the origin definition (or in the remotes definitions, see bellow):

{
  "type": "git",
  "origin": {
    (...)
  },
  "branch": "<branch, defaults to master>"
}

Other remotes

You can specify additional remotes:

{
  "type": "git",
  "origin": {
    (...)
  }
  "remotes": {
    "remote1": {
       (...)
    },
    (...)
    "remoteN": {
       (...)
    },
  }
}

Each remote definition use the same syntax as the origin definition.