Chapter 42. 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. 42.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 Create a post-commit Git hook file: Set the permissions of the post-commit file to 755 : Add #!/bin/bash and any required code to the post-commit file, for example: To push all changes to a remote repository: To log a message: To execute code of another file: 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 . 42.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.4 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 In Business Central, go to Menu Projects . Select or create the space that you want to import the Git projects into. Click on the right side of the screen and select Import Project . 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. 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. In a command terminal, navigate to the hooks folder located in the repository Git folder of the project. For example: Create a post-commit file that pushes changes to the remote Git repository. For example: For more information about creating post-commit Git hooks, see Section 42.1, "Creating post-commit Git hooks" . Optional: To check that the configuration was successful, create a guided rule in Business Central: In Business Central go to Menu Projects Add Asset Guided Rule . On the Create new Guided Rule page, enter the required information. Click Ok . Business Central automatically pushes all changes to the remote repository. Additional resources Customizing Git - Git Hooks 42.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.4 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 In a command terminal, navigate to the hooks folder located in the repository Git folder of the project. For example: Create a post-commit file that pushes changes to the remote Git repository. For example: For more information about creating post-commit Git hooks, see Section 42.1, "Creating post-commit Git hooks" . Optional: To check that the configuration was successful, create a guided rule in Business Central: In Business Central go to Menu Projects Add Asset Guided Rule . On the Create new Guided Rule page, enter the required information. Click Ok . Business Central automatically pushes all changes to the remote repository. 42.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.4 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 Create a post-commit Git hook in a directory on your local system. For more information about creating post-commit Git hooks, see Section 42.1, "Creating post-commit Git hooks" . 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: Use the -Dorg.uberfire.nio.git.hooks environment variable when executing Business Central. For example: Start Business Central. The post-commit Git hook is copied to all Business Central internal repositories and project repositories. Additional resources Customizing Git - Git Hooks 42.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.4 server instance. Java Development Kit (JDK) 8 is installed. Maven is installed. Procedure In a terminal window, clone the GitHub repository to your system: Navigate to the cloned repository: Execute a Maven clean install: Create a /hooks folder in your EAP_HOME directory: Copy the git-push-2.1-SNAPSHOT.jar to the EAP_HOME /hooks/ folder: Optional: To create a template .gitremote configuration file, run git-push-2.1-SNAPSHOT.jar : Example template .gitremote configuration file Modify the .gitremote configuration file parameters. Table 42.1. Example .gitremote parameters Parameter Description 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. Create a post-commit Git hook file in EAP_HOME /hooks : Set the permissions of the post-commit file to 755 : Add #!/bin/bash and code to execute git-push-2.1-SNAPSHOT.jar to the post-commit file: Start Business Central with the -Dorg.uberfire.nio.git.hooks environment variable set. For example: 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 . 42.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). 42.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 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: 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. 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: 42.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 42.2. Git hook UI notification types Exit code Customized message UI 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. 42.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.

Commands:
touch post-commit
chmod 755 post-commit
#!/bin/bash git push origin +master
#!/bin/bash echo 'Hello World'
#!/bin/bash java -jar _EAP_HOME_/bin/.niogit/<SPACE>/<PROJECT_NAME>.git/hooks/git-push.jar
cd _EAP_HOME_/bin/.niogit/<SPACE>/<PROJECT_NAME>.git/hooks
#!/bin/sh git push origin +master
cd _EAP_HOME_/bin/.niogit/<SPACE>/<PROJECT_NAME>.git/hooks
#!/bin/sh git push origin +master
<system-properties> <property name="org.uberfire.nio.git.hooks" value="_EAP_HOME_/hooks"> </property> </system-properties>
./standalone.sh -c standalone-full.xml -Dorg.uberfire.nio.git.hooks=_EAP_HOME_/hooks
git clone https://github.com/kiegroup/bc-git-integration-push.git
cd bc-git-integration-push
mvn clean install
mkdir -p _EAP_HOME_/hooks/
cp bc-git-integration-push/target/git-push-2.1-SNAPSHOT.jar _EAP_HOME_/hooks/
java -jar git-push-2.1-SNAPSHOT.jar
#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
touch post-commit
chmod 755 post-commit
echo "#\!/bin/bash\njava -jar USDAPP_SERVER_HOME/hooks/git-push-2.1-SNAPSHOT.jar" > hooks/post-commit
./standalone.sh -c standalone-full.xml -Dorg.uberfire.nio.git.hooks=_EAP_HOME_/hooks
0=Success! All working as expected. 1=Warning! Please check the logs and advise your admin. . . 31=Error! Please advise your admin immediately.
<system-properties> <property name="appformer.git.hooks.bundle" value="/opt/jboss-as/git-hooks-messages/Messages.properties"> </property> </system-properties>