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.
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:$ touch post-commit
Set the permissions of the
post-commit
file to755
:$ chmod 755 post-commit
Add
#!/bin/bash
and any required code to thepost-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
NoteTo 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 environmentPATH
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.
ImportantUse 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:$ cd _EAP_HOME_/bin/.niogit/<SPACE>/<PROJECT_NAME>.git/hooks
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 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.
-
In Business Central go to Menu
Additional resources
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 environmentPATH
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:$ cd _EAP_HOME_/bin/.niogit/<SPACE>/<PROJECT_NAME>.git/hooks
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 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.
-
In Business Central go to Menu
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.
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 environmentPATH
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 thestandalone.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
Start Business Central.
The post-commit Git hook is copied to all Business Central internal repositories and project repositories.
Additional resources
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:
$ git clone https://github.com/kiegroup/bc-git-integration-push.git
Navigate to the cloned repository:
$ cd bc-git-integration-push
Execute a Maven clean install:
$ mvn clean install
Create a
/hooks
folder in yourEAP_HOME
directory:$ mkdir -p _EAP_HOME_/hooks/
Copy the
git-push-2.1-SNAPSHOT.jar
to theEAP_HOME/hooks/
folder:$ cp bc-git-integration-push/target/git-push-2.1-SNAPSHOT.jar _EAP_HOME_/hooks/
Optional: To create a template
.gitremote
configuration file, rungit-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
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
andpassword
based unsecured connection. Note: If this is not set a warning is displayed that you are using an unsecured connection. Not required if apassword
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 inEAP_HOME/hooks
:$ touch post-commit
Set the permissions of the
post-commit
file to755
:$ chmod 755 post-commit
Add
#!/bin/bash
and code to executegit-push-2.1-SNAPSHOT.jar
to thepost-commit
file:$ echo "#\!/bin/bash\njava -jar $APP_SERVER_HOME/hooks/git-push-2.1-SNAPSHOT.jar" > hooks/post-commit
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
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:
0=Success! All working as expected. 1=Warning! Please check the logs and advise your admin. . . 31=Error! Please advise your admin immediately.
NoteIt 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.
ImportantThe 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 aMessages.properties
file:<system-properties> <property name="appformer.git.hooks.bundle" value="/opt/jboss-as/git-hooks-messages/Messages.properties"> </property> ... </system-properties>
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.
Exit code | Customized message | UI notification color |
---|---|---|
| Success! All working as expected. | Green |
| Warning! Please check the logs and advise your admin. | Orange |
| Error! Please advise your admin immediately. | Red |
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.