Chapter 18. Repository hooks

In Business Central, you can use scripts, known as hooks, to configure the repository to trigger a specified action every time a particular event happens. For more information about Git hooks, see Customizing Git Hooks.

18.1. Configuring Git hooks

You can use Business Central to automatically push changes to a remote repository using Git hooks by configuring the post-commit hook.

Note

Currently only post-commit hooks are supported. Post-commit hooks are triggered after the commit process finishes.

Prerequisites

  • Red Hat Decision Manager is installed in a Red Hat JBoss EAP 7.2 server instance.
  • Red Hat Decision 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 Menu → Projects.
  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 Decision Manager version. The KJAR content must be in the root of the repository.

  6. In a command terminal, navigate to the repository folder: 

    cd JBOSS_HOME/bin/.niogit/<SPACE>/REPOSITORY_NAME.git
  7. Create a post-commit file in a hooks folder with permissions set to rwxr—​r--. For example, JBOSS_HOME/bin/.niogit/<SPACE>/REPOSITORY_NAME.git/hooks/post-commit.

  8. Add the following content to the post-commit file: 

    #!/bin/sh
git push origin +master

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

    1. In Business Central go to Menu → Projects → Add Asset → Guided 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.

You can specify a directory with the hook file for the value of the org.uberfire.nio.git.hooks system property. This directory is copied to the newly created Git repositories. See the following example of a standalone.xml file with this setting: 

<system-properties>
  <property name="org.uberfire.nio.git.hooks" value="/opt/jboss-as/git-hooks">
  </property>
  ...
</system-properties>

Additional resources

18.2. 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).

18.3. 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>

18.3.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 18.1. 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.

18.3.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 language, if there are no available translations for that language it will use the entries from the original Messages.properties file.