Pineapple Git plugin

Introduction

Overview

Invoking the plugin

The plugin is invoked by when the core component is used by one of the Pineapple clients. To trigger invocation by the core component the plugin needs to be configured.

Configuration

Two steps are needed to configure the plugin:

Define resource: Define resource which enables usage of the the plugin. The resource enables usage by:
- Definition of connectivity information used by the Git plugin to locate and connect to the remote Git repository defined by the resource.
- Definition of a mapping between the resource ID (e.g. some user defined key referenced from models) and the plugin ID (e.g. the Java package name which implements the plugin: com.alpha.pineapple.plugin.git.
Define the module model and add content to the model by defining a set of entities which are processed at the targeted resource(s). The entities are processed in sequence when the plugin is invoked with the model. The model is defined using the The Git plugin schema.

For more info about configuration of plugins:

For info about resources and credentials read the Environment configuration document.
For info about modules and module models read the Modules configuration document.

Supported operations by the plugin

The plugin supports the operations:

deploy-configuration

For more information about the default operations, refer to the Operation and workflow reference.

Execution of the deploy-configuration operation

When invoked with this operation the plugin will traverse the module model and create all the Git entities (e.g. repository) defined in the model:

Repository: The repository is cloned from the remote repository defined by the resource. If the repository already exist locally then it is deleted and the content of the remote repository is cloned.

Define resource

The purpose of defining a resource for this plugin is twofold:

Define a mapping between the resource ID and the plugin ID. The resource ID is the user defined key which is referenced from module models which are targeting the resource. The plugin ID is the Java package name which implements the plugin: com.alpha.pineapple.plugin.git.
Define connectivity information used by the Git plugin to connect to the remote repository.

To define a new resource, add a resource element to the target environment in the configuration file ${pineapple.home.dir}/conf/resources.xml:

<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns="http://pineapple.dev.java.net/ns/environment_1_0" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  
  <environments>
    <environment id="local" >
      <resources>
        <resource id="git-pineapple-example-repo" plugin-id="com.alpha.pineapple.plugin.git" />
          <property key="uri" value="https://github.com/athrane/pineapple-git-plugin-test-repository.git"/>          
        </resource>
      </resources>
    </environment>                                                              
  </environments>
</configuration>

For all the details about configuration of environments and resources, please visit the Environment Configuration Reference.

The semantics of the resource element is:

The `id` attribute

Identifies the resource uniquely in the current environment. This ID is referenced from models which intends to use the plugin.

The `plugin-id` element

The plugin ID defines the name of the Java package which implements the plugin. The plugin ID for this plugin is: com.alpha.pineapple.plugin.git.

The `property` attributes(s)

Mandatory properties used by the plugin:

uri - URI of the remote Git repository which is accessed by the plugin.

A module defines the input used by Pineapple to execute operations. A module is defined by a directory layout. Part of a module is the model(s) which defines what happens when the module is invoked. A model is put together by one or more sub models from different plugins. Each plugin defines its own schema for its particular model

The Git plugin schema

This plugin defines a schema named The Git plugin schema which defines the http://pineapple.dev.java.net/ns/plugin/git_1_0 namespace. For more information about where the schema can be found, refer to the Schema locations for plugins page.

Name and location of the the module model file

The list of entities which should be processed when the plugin is invoked are defined in the module model files which are located at ${module-dir}/models/${environment}.xml where:

${module-dir} is the module root directory which identifies the module with a unique name and version.
${environment}.xml is a module model file for a target environment, with ${environment} substituted with the environment name, e.g. linux-vagrant.xml for an environment named linux-vagrant.

If the model file doesn't exist for an environment where the plugin should be used, then create the model file and name it after the target environment, e.g. linux-vagrant.xml for an environment named linux-vagrant.

The module model configuration schema

Module model files are defined using the module model configuration schema which defines the http://pineapple.dev.java.net/ns/module_model_1_0 namespace. Since module model files contain elements from multiple namespaces all the elements and attributes should be qualified. The header and root element should be defined as (look in the Modules configuration document for more details):

This example shows definition of the minimal model file for linux-vagrant:

<?xml version="1.0" encoding="UTF-8"?>
<mmd:models xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:mmd="http://pineapple.dev.java.net/ns/module_model_1_0" />

Adding the plugin schema to the model

The next step is to include the The Git plugin schema to get access to the entities defined by the schema:

<?xml version="1.0" encoding="UTF-8"?>
<mmd:models xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:mmd="http://pineapple.dev.java.net/ns/module_model_1_0"                 
  xmlns:gp="http://pineapple.dev.java.net/ns/plugin/git_1_0" />

Now we have a minimal module model file with three namespaces:

xs: The basic XMLSchema schema which is only used in the root element of the document.
mmd: The module model schema which is used to define the skeleton of a model file.
gp: The Git plugin schema which is used to define Git resources.

Defining the model which targets resources

Add a new model stanza with a target-resource attribute. The value of the target-resource should match the id of the resource which was defined previously in the section Define resource, e.g. git-pineapple-example-repo:

<?xml version="1.0" encoding="UTF-8"?>
<mmd:models xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:mmd="http://pineapple.dev.java.net/ns/module_model_1_0"                 
  xmlns:gp="http://pineapple.dev.java.net/ns/plugin/git_1_0" />
  
  <mmd:model target-resource="git-pineapple-example-repo">              
    <mmd:content />                             
  </mmd:model>
</mmd:models>

Add content to the model which uses the plugin through the git-pineapple-example-repo reference:

<?xml version="1.0" encoding="UTF-8"?>
<mmd:models xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:mmd="http://pineapple.dev.java.net/ns/module_model_1_0"                 
  xmlns:gp="http://pineapple.dev.java.net/ns/plugin/git_1_0" />
  
  <mmd:model target-resource="git-pineapple-example-repo">              
    <mmd:content>
      <gp:git>
      </gp:git>                 
    </mmd:content>                                                                                                                                                                              
  </mmd:model>
</mmd:models>

Define Git entities the module model

Define a set of entities which should be processed when Pineapple is invoked with the model:

<?xml version="1.0" encoding="UTF-8"?>
<mmd:models xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:mmd="http://pineapple.dev.java.net/ns/module_model_1_0"                 
  xmlns:gp="http://pineapple.dev.java.net/ns/plugin/git_1_0" />
  
  <mmd:model target-resource="git-node">                
    <mmd:content>
      <gp:git>
        <gp:repository destination="modules:pineapple-git-plugin-test-repository" branch="master" />
      </gp:git>                 
    </mmd:content>
  </mmd:model>
</mmd:models>

Repository

Defines a Git repository.

  <gp:repository destination="modules:pineapple-git-plugin-test-repository" branch="master" />

Operation semantics:

deploy-configuration: Clones remote repository. The repository is cloned from the remote repository defined by the resource. If the repository already exist locally then it is deleted and the content of the remote repository is cloned.

The semantics of the attributes are:

`branch` attribute

Optional attribute. Defines the branch which is cloned, when a remote repository is cloned. Default value is master.

Example: HEAD and 1.0.

`destination` attribute

Optional attribute. Defines the local destination where the cloned repository is stored, when a remote repository is cloned. The value can be prefixed with the modules: identifier. If the identifier is present then Pineapple will interpret the path as an relative path where the root is the Pineapple modules directory. If the identifier is present then the path is resolved with the root in Pineapple modules directory. Afterwards the cloned repository is positioned and can be used as a module if the repository contains a module.

Default value is modules:project where the project is resolved from the project part of the URI defined for Git resource. See Git on the Server - The Protocols.

Examples: modules:pineapple-git-plugin-test-repository and /tmp/myrepo.