Chapter 43. Git hooks and remote Git repository integration

Git hooks are bash scripts that execute before or after Git events such as git commit or git push. In Business Central, you can use Git hooks to configure repositories to trigger specified actions every time events happen. For more information about Git hooks, see Customizing Git Hooks.

You can integrate remote Git repositories with Business Central by using post-commit Git hooks. This enables you to automate content replication between Business Central and remote repositories. For example, you can implement a real-time backup strategy where changes you make to your Business Central projects are replicated to your remote Git repositories.

Note

Business Central only supports post-commit Git hooks.

A post-commit Git hook executes after every commit as a sync operation. Business Central waits for the post-commit bash to complete and no other write operation occurs in the repository.

43.1. Creating post-commit Git hooks

You can create a post-commit Git hook bash script file that executes code contained in that file or execute code from a different file such as a Java program.

Procedure

  1. Create a post-commit Git hook file:

    $ touch post-commit
  2. Set the permissions of the post-commit file to 755:

    $ chmod 755 post-commit
  3. Add #!/bin/bash and any required code to the post-commit file, for example:

    • To push all changes to a remote repository:

      #!/bin/bash
      git push origin +master
    • To log a message:

      #!/bin/bash
      echo 'Hello World'
    • To execute code of another file:

      #!/bin/bash
      java -jar _EAP_HOME_/bin/.niogit/<SPACE>/<PROJECT_NAME>.git/hooks/git-push.jar
      Note

      To use post-commit Git hooks that execute Java code, you must use the following Java libraries:

      • JGit: Used to interact with internal Business Central Git repositories.
      • GitHub API for Java: Used to communicate with GitHub.

      For more information about post-commit Git hook and Java code examples, see Business Central post-commit Git Hooks Integration.

43.2. Importing remote Git repositories

You can import a remote Git repository in to Business Central and configure a post-commit Git hook to automatically push changes to that remote repository.

Prerequisites

  • Red Hat Process Automation Manager is installed in a Red Hat JBoss EAP 7.3 server instance.
  • Red Hat Process Automation Manager projects exist in an external Git repository.
  • Read access credentials for the external Git repository.
  • (For Windows) Cygwin is installed with the Git package added during installation and the path to the Cygwin /bin folder is added to your environment PATH variable. For example, C:\cygwin64\bin. For more information about Cygwin installation, see Installing and Updating Cygwin Packages.

Procedure

  1. In Business Central, go to MenuProjects.
  2. Select or create the space that you want to import the Git projects into.
  3. Click dots on the right side of the screen and select Import Project.
  4. In the Import Project window, enter the URL of your Git repository, for example, https://github.com/USERNAME/REPOSITORY_NAME.git, and the credentials for the Git repository.
  5. Click Import.

    The project is added to the Business Central Git repository and is then available in the space.

    Important

    Use the HTTPS or Git protocol instead of a SCP-style SSH URL. Business Central does not support the basic SSH URL and an error appears if you use this URL.

    You must have your public ssh key configured in your Git provider.

    The Git repository must be a KJAR project, containing only a single KJAR that is compatible with the Red Hat Process Automation Manager version. The KJAR content must be in the root of the repository.

  6. In a command terminal, navigate to the hooks folder located in the repository Git folder of the project. For example:

    $ cd _EAP_HOME_/bin/.niogit/<SPACE>/<PROJECT_NAME>.git/hooks
  7. Create a post-commit file that pushes changes to the remote Git repository. For example:

    #!/bin/sh
    git push origin +master

    For more information about creating post-commit Git hooks, see Section 43.1, “Creating post-commit Git hooks”.

  8. Optional: To check that the configuration was successful, create a guided rule in Business Central:

    1. In Business Central go to MenuProjectsAdd AssetGuided Rule.
    2. On the Create new Guided Rule page, enter the required information.
    3. Click Ok.

      Business Central automatically pushes all changes to the remote repository.

Additional resources

43.3. Configuring Git hooks for existing remote Git project repositories

If you have an existing remote Git repository project you can create a post-commit Git hook in a remote Git repository of that existing project and integrate the remote Git repository with Business Central.

Prerequisites

  • Red Hat Process Automation Manager is installed in a Red Hat JBoss EAP 7.3 server instance.
  • Red Hat Process Automation Manager projects exist in an external Git repository.
  • Read access credentials for the external Git repository.
  • (For Windows operating system) Cygwin is installed with the Git package added during installation and the path to the Cygwin /bin folder is added to your environment PATH variable. For example, C:\cygwin64\bin. For more information about Cygwin installation, see Installing and Updating Cygwin Packages.

Procedure

  1. In a command terminal, navigate to the hooks folder located in the repository Git folder of the project. For example:

    $ cd _EAP_HOME_/bin/.niogit/<SPACE>/<PROJECT_NAME>.git/hooks
  2. Create a post-commit file that pushes changes to the remote Git repository. For example:

    #!/bin/sh
    git push origin +master

    For more information about creating post-commit Git hooks, see Section 43.1, “Creating post-commit Git hooks”.

  3. Optional: To check that the configuration was successful, create a guided rule in Business Central:

    1. In Business Central go to MenuProjectsAdd AssetGuided Rule.
    2. On the Create new Guided Rule page, enter the required information.
    3. Click Ok.

      Business Central automatically pushes all changes to the remote repository.

43.4. Configuring Git hooks as a system property for Business Central

If you do not have an existing Git repository project or if you want to apply post-commit Git hooks to a large number of project repositories you can specify a directory containing a hook file for the value of the org.uberfire.nio.git.hooks system property. This directory is copied to the Git repositories.

Note

If you specify the org.uberfire.nio.git.hooks system property, all Business Central internal repositories and project repositories use the post-commit Git hook. You should only use fully qualified paths in your script.

Prerequisites

  • Red Hat Process Automation Manager is installed in a Red Hat JBoss EAP 7.3 server instance.
  • (For Windows operating system) Cygwin is installed with the Git package added during installation and the path to the Cygwin /bin folder is added to your environment PATH variable. For example, C:\cygwin64\bin. For more information about Cygwin installation, see Installing and Updating Cygwin Packages.

Procedure

  1. Create a post-commit Git hook in a directory on your local system.

    For more information about creating post-commit Git hooks, see Section 43.1, “Creating post-commit Git hooks”.

  2. To specify the directory with the hook file for the value of the org.uberfire.nio.git.hooks system property, do one of the following tasks:

    • Add the org.uberfire.nio.git.hooks system property to the standalone.xml file. For example:

      <system-properties>
        <property name="org.uberfire.nio.git.hooks" value="_EAP_HOME_/hooks">
        </property>
        ...
      </system-properties>
    • Use the -Dorg.uberfire.nio.git.hooks environment variable when executing Business Central. For example:

      $ ./standalone.sh -c standalone-full.xml -Dorg.uberfire.nio.git.hooks=_EAP_HOME_/hooks
  3. Start Business Central.

    The post-commit Git hook is copied to all Business Central internal repositories and project repositories.

Additional resources

43.5. Integrating remote Git repositories

In the following example, you use a post-commit Git hook and Java code to integrate Business Central with a remote Git repository. For the Java code example, see Business Central post-commit Git Hooks Integration. The example provides the following functionality:

  • Automatic generation of the template .gitremote configuration file
  • Validation of the .gitremote configuration file for required parameters
  • Patterns defined in the ignore parameter of the .gitremote file are ignored by Git
  • Message and notification output to users
  • Support for GitLab and GitHub token authentication
  • Support for GitLab group and subgroup project creation
  • Support for GitHub organization repository creation

Prerequisites

  • Red Hat Process Automation Manager is installed in a Red Hat JBoss EAP 7.3 server instance.
  • Java Development Kit (JDK) 8 is installed.
  • Maven is installed.

Procedure

  1. In a terminal window, clone the GitHub repository to your system:

    $ git clone https://github.com/kiegroup/bc-git-integration-push.git
  2. Navigate to the cloned repository:

    $ cd bc-git-integration-push
  3. Execute a Maven clean install:

    $ mvn clean install
  4. Create a /hooks folder in your EAP_HOME directory:

    $ mkdir -p _EAP_HOME_/hooks/
  5. Copy the git-push-2.1-SNAPSHOT.jar to the EAP_HOME/hooks/ folder:

    $ cp bc-git-integration-push/target/git-push-2.1-SNAPSHOT.jar _EAP_HOME_/hooks/
  6. Optional: To create a template .gitremote configuration file, run git-push-2.1-SNAPSHOT.jar:

    $ java -jar git-push-2.1-SNAPSHOT.jar

    Example template .gitremote configuration file

    #This is an auto generated template empty property file
    provider=GIT_HUB
    login=
    password=
    token=
    remoteGitUrl=https://api.github.com/
    useSSH=false
    ignore=.*demo.*, test.*
    githubOrg=OrgName
    gitlabGroup=Group/subgroup

  7. Modify the .gitremote configuration file parameters.

    Table 43.1. Example .gitremote parameters

    ParameterDescription

    provider

    The Git provider. Only two values are accepted: GIT_HUB and GIT_LAB. Required

    login

    The user name for the Git provider. Required

    password

    A plain text password. Not required if a token is provided.

    token

    A generated token to replace the username and password based unsecured connection. Note: If this is not set a warning is displayed that you are using an unsecured connection. Not required if a password is provided. Note: GitLab only supports token authentication.

    remoteGitUrl

    A public provider URL or a locally hosted enterprise for any provider. Required. Note: The public GitHub URL should be the API URL. For example, api.github.com.

    useSSH

    Boolean to allow the SSH protocol to push changes to the remote repository. Optional. Default = false. Note: This parameter uses the local ~/.ssh/ directory to obtain the SSH configuration.

    ignore

    A comma separated regular expressions to ignore project names that match any of these expressions. Optional.

    githubOrg

    Defines the repository organization if GitHub is used as the provider. Optional.

    gitlabGroup

    Defines the repository group and subgroup if GitLab is used as the provider Optional.

  8. Create a post-commit Git hook file in EAP_HOME/hooks:

    $ touch post-commit
  9. Set the permissions of the post-commit file to 755:

    $ chmod 755 post-commit
  10. Add #!/bin/bash and code to execute git-push-2.1-SNAPSHOT.jar to the post-commit file:

    $ echo "#\!/bin/bash\njava -jar $APP_SERVER_HOME/hooks/git-push-2.1-SNAPSHOT.jar" > hooks/post-commit
  11. Start Business Central with the -Dorg.uberfire.nio.git.hooks environment variable set. For example:

    $ ./standalone.sh -c standalone-full.xml -Dorg.uberfire.nio.git.hooks=_EAP_HOME_/hooks
Note

To use post-commit Git hooks that execute Java code, you must use the following Java libraries:

  • JGit: Used to interact with internal Business Central Git repositories.
  • GitHub API for Java: Used to communicate with GitHub.

For more information about post-commit Git hook and Java code examples, see Business Central post-commit Git Hooks Integration.

43.6. Git hook exit codes

When a Git hook exits an integer value is returned which determines the status of the Git hook execution. This integer value is known as a Git hook exit code. The execution status can be a success (1), warning (2 to 30) or error (31 to 255).

43.7. Customizing Git hook notifications

Business Central provides a mechanism that enables users to receive customized Git hook notifications based on the hook exit codes.

To enable the notification mechanism you must create a *.properties file containing the custom messages and then specify the path to that file as the value of the appformer.git.hooks.bundle system property.

Procedure

  1. Create the *.properties file and add a line for each exit code with a corresponding message in the following format:

    <exit_code>=<display_message>

    The <exit_code> is the Git hook exit code and the <display_message> is the custom message that is displayed to a user.

    For example:

    0=Success! All working as expected.
    1=Warning! Please check the logs and advise your admin.
    .
    .
    31=Error! Please advise your admin immediately.
    Note

    It is not necessary to define all the possible exit codes in the *.properties file. Notifications appear only for the exit codes defined in the *.properties file.

    Important

    The notification service only supports the ISO 8859-1 (LATIN 1) character set in the properties file. If you want to use extended characters, please use their escaped Unicode character code sequences.

  2. To enable Git hook notifications, specify the path to the file as the value of the appformer.git.hooks.bundle system property.

    See the following example of a standalone.xml file with the setting that points to a Messages.properties file:

    <system-properties>
      <property name="appformer.git.hooks.bundle" value="/opt/jboss-as/git-hooks-messages/Messages.properties">
      </property>
      ...
    </system-properties>

43.7.1. Git hook notifications in Business Central

You can view Git hook notifications in Business Central. There are three Git hook exit code notification types.

Table 43.2. Git hook UI notification types

Exit codeCustomized messageUI notification color

0

Success! All working as expected.

Green

1 to 30

Warning! Please check the logs and advise your admin.

Orange

31 to 255

Error! Please advise your admin immediately.

Red

Important

UNIX machines only support error codes between 0 (success) to 255 (error), any exit code outside of this range will end up being converted into a different code which may cause showing a wrong notification message.

Windows machines don’t have this limitation and support a wide range of exit codes.

43.7.2. Git hook notification internationalization support

You can internationalize notification messages by placing additional properties files in the same path as the original properties file specified as the appformer.git.hooks.bundle system property.

The name of the different localized files must be <filename>_<lang>.properties, where the <filename> is the same as the original. For example, where the system property points to Messages.properties, you can create Messages_en.properties for English, Messages_fr.properties for French, or Messages_it.properties for Italian.

The notification service will choose the properties file based on the user’s language, if there are no available translations for that language it will use the entries from the original Messages.properties file.