Red Hat Training

A Red Hat training course is available for Red Hat Process Automation Manager

Chapter 16. 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.

16.1. Configuring git hooks

Business Central can automatically push changes to a remote repository using Git hooks. After you configure the post-commit hook, Business Central automatically pushes your changes to the remote repository.

Note

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

Prerequisites

  • Red Hat Process Automation Manager projects exist in an external Git repository.
  • Credentials required for read access to that external Git repository are available.

Procedure

  1. Log in to Business Central.
  2. Select Menu → Projects.
  3. Select or create the space into which you want to import the projects.
  4. Click dots on the right side of the screen and select Import Project.

  5. In the Import Project window, enter the URL (for example, https://github.com/USERNAME/REPOSITORY_NAME.git) and credentials for the Git repository that contains the project that you want to import and click Import.

    The project is added to the Business Central Git repository and is available in the created or default 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.

  6. In a terminal window, change to the created repository. 

    cd JBOSS_HOME/bin/.niogit/REPOSITORY_NAME.git

  7. Create the post-commit file in the JBOSS_HOME/bin/.niogit/REPOSITORY_NAME.git/hooks directory, set the permissions to rwxr—​r-- and add the following content: 

    #!/bin/sh
git push origin master

  8. Make sure that the configuration was successful by creating a new guided rule in Business Central:

    1. Select Menu → Projects → Add Asset → Guided Rule.
    2. Fill in the required information in the displayed Create new Guided Rule window.

    3. Click Ok.

      Business Central automatically pushes all changes to the remote repository.

You can also specify the org.uberfire.nio.git.hooks system property. Specify a directory with default hook files as the value for this property. This directory will be copied to the newly created Git repositories. See the following example of a standalone.xml file with this setting below: 

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

16.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, warning or failure.

16.2.1. Types of exit codes

Business Central has the following three types of exit codes:

Successful notification

0: Success. A git hook that exits with code 0 displays a success notification in the user interface.

Warning notification

1..30: Warning. A git hook that exits with a code between 1 and 30 (inclusive) will display a warning notification in user interface.

Error notification

Anything else: Error. Any other code number will be displayed as an error notification.

Important

UNIX systems only support error codes between 0 (success) and 255 (error). Any exit code outside of this range is converted to a different code which might result in displaying a wrong notification message. Windows systems don’t have this limitation and can support a wide range of exit codes.

16.3. Customizing git hook notifications

Business Central provides a mechanism that enables users to receive feedback about git hook executions using customized messages based on a hook’s exit code.

Procedure

  1. To enable notifications, in the standalone.xml file set the appformer.git.hooks.bundle system property to point to a *.properties file containing the custom messages for each exit code.

    For example: 

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

  2. To display the messages, each line of the *.properties must have the following format:

    <exit_code>=<display_message>

    where, <exit_code> is the git hook exit code and <display_message> is the custom message that is displayed to a user.

    Exit code messages with this format appear similar to the following example: 

    0=Success
1=Display Message 1
.
.
31=Display Message 31
Note

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

16.3.1. Internationalize git hook notifications

You can internationalize the notification messages by placing different *.properties files in the directory specified for the appformer.git.hooks.bundle system property. The names of the localized files have the format <filename>_<lang>.properties. These files must contain the same entries as in the original file.

For example, you have specified the system property to point to Messages.properties. Now you can create localized message properties files like Messages_en.properties for English, Messages_fr.properties for French, Messages_it.properties for Italian, and so on. The notification service will choose the one based on the user language and if there are no available translations for a language then it will use the default ones specified in the Messages.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 escape them using their Unicode code.