VCSI: Git Delivery Method in OIEP

The Git Delivery method delivers files produced by the outbound integration endpoint (OIEP) processing engine and a configured STEPXML Splitter post-processor to a branch in a remote Git repository. In this scenario, the entire branch is replaced with the current objects delivered by the OIEP as a flat hierarchy, where all files delivered are directly under the branch. Refer to https://git-scm.com for more information about Git.

When using this delivery method on an on-premises STEP system, the delivery to Git can be performed via a configured local directory accessible from all application servers in the cluster (refer to the Local git repository URI section below). With this setup, the delivery method first checks if the local delivery directory is Git enabled.

If the local delivery directory is Git enabled, the following operations are performed:

Git fetch
Git checkout (of configured branch)
Git hard reset
Git pull (if branch exists in remote)

If the local delivery directory is not Git enabled, the following operations are performed:

Git clone
Git checkout (of configured branch)

On Stibo Systems SaaS environments, a temporary local directory is always used and the second approach (clone and checkout) is used.

Note: The remote repository cannot be empty. At least one branch with one file must exist (e.g., the 'main' branch and the README.md file).

The locally checked-out branch is now in sync with the remote branch, and the following operations are performed:

Files produced by the OIEP are written to the local directory
Files present in the local directory but not in the delivery are deleted
Git stage
Git commit
Git push

Prerequisites

Important: For on-premises systems, this feature requires the configuration-management component.

Changes to shared configuration properties on the STEP application server are required to populate the dropdown list delivery options. Changing these properties does not require a system restart.

Prior to configuring the Git Delivery method, add the desired case-sensitive properties described below.

Note: In the properties mentioned below, use a unique set of variable integers in the property names, for example, 1, 2, 3. When duplicate integers exist, only the last value is displayed in the dialog.

For on-prem systems, the Local git repository URI parameter defines a Uniform Resource Identifier (URI) for the local directory where the synchronized configuration files are stored. The values are read from the case-sensitive GitDelivery.LocalRepoUri.[integer] property. For example:
```
GitDelivery.LocalRepoUri.1=/workarea/conf-attributes
GitDelivery.LocalRepoUri.2=/workarea/conf-all			
```
These settings would allow users to select between the values '/workarea/conf-attributes' and '/workarea/conf-all' for the parameter in the dropdown.

Do not set the Local git repository URI property for Stibo Systems SaaS environments.
For both on-prem and Stibo Systems SaaS environments, the Remote git repository URI parameter defines the URI for the remote repository. The values are read from the case-sensitive GitDelivery.RemoteRepoUri.[integer] property. For example:
```
GitDelivery.RemoteRepoUri.1=https://gitlab.com/john-smith/step-conf.git
GitDelivery.RemoteRepoUri.2=git@bitbucket.org:john-smith/smithrepo.git
```
Note: For internally hosted Git setups, ensure that any firewall access rules, IP white-listing, or ports (tcp/22 or similar) are configured to allow the STEP server(s) to access the needed Git repository.
The Git Branch parameter defines the name of the branch to which the delivery is published. The values are read from the case-sensitive GitDelivery.Branch.[integer] property. For example:
```
GitDelivery.Branch.1=step-dev-1 
GitDelivery.Branch.2=step-q
```
The Repository username parameter in the dialog defines the options available in the dropdown list and supports authentication via HTTPS with PAT entered in the Repository User Password field in the dialog (discussed in VCSI: Supported Authentication Methods per Git Service in OIEP). The values read from the case-sensitive GitDelivery.RemoteRepoUsername.[integer] property. For example:
```
GitDelivery.RemoteRepoUsername.1=john.smith 
GitDelivery.RemoteRepoUsername.2=julie.baker
```
The Path to private key when using ssh parameter must contain the full path to the private SSH key file. The values are read from the case-sensitive GetDelivery.SshPrivateKeyUri.[integer] property. For example:
```
GitDelivery.SshPrivateKeyUri.1=/home/stibosw/.ssh/git_rsa4096_key
GitDelivery.SshPrivateKeyUri.2=/workarea/.ssh/gitlab_rsa4096_enc_key
GitDelivery.SshPrivateKeyUri.3=/upload/.ssh/bitbucket_rsa4096_key
```
Configure SSH Connection

To connect via SSH, the Path to Private Key When Using SSH parameter defines the remote repository RSA SSH private key generated using the old OpenSSH format and ed25519. The generated key file must be accessible to the application server through shared storage or SFTP.

Important: PuTTYgen (.ppk) SSH keys are not supported by STEP. Using an unsupported key type results in an 'invalid private key' error.

Follow these steps to generate a valid private SSH key:
1. Use ssh -V to check the version on your system and then generate a key.
  - With OpenSSH versions prior to 7.8, use the following command to generate the new OpenSSH format key:
```
ssh-keygen -t rsa -b 4096 -C <comment> -f <keyfile_name>
```
    For example:
```
ssh-keygen -t rsa -b 4096 -C john.smith@acme.com -f git_rsa4096_key
```
  - With OpenSSH versions 7.8+, generated keys default to the new OpenSSH format. To generate keys in the old format, use the following command:
```
ssh-keygen -t rsa -b 4096 -C john.smith@acme.com -m PEM -f git_rsa4096_key
```
    Important: While the general approach and commands are the same with later versions of OpenSHH, the -m PEM argument shown above is needed with versions 7.8+.
2. Add the public version of the SSH key (e.g., git_rsa4096_key.pub) to your GitLab or Bitbucket account. Failure to add the public key to your account results in a 'Not authorized' error.
  
  For a general overview of supported authentication methods, and details on GitHub and Bitbucket, refer to the VCSI: Supported Authentication Methods per Git Service in OIEP topic.

Configuration

For information on a parameter, hover over the parameter field to display help text.

On the Configuration tab, in the Delivery Method area, click Edit Delivery.
In Select Delivery Method, choose Git Delivery.

Note: The parameter dropdown options are defined by the properties outlined in the Prerequisites section above.
For a local delivery, in Local git repository URI, from the dropdown, select a URI for the local directory via which configuration files are synchronized.

For Stibo Systems SaaS environments, leave this parameter blank.
For a remote delivery, in Remote git repository URI, from the dropdown, select a URI for the remote repository.
In Git branch, from the dropdown, select the name of the branch where the delivery is published.
In Author name, from the dropdown, select an author name for the Git commit.
In Author email, from the dropdown, select an author email for the Git commit.
In Git Access Method, select the HTTPS or SSH radio button and provide additional values as required.
- For HTTPS (using Basic authentication or Personal Access Token (PAT)):
  - In Repository username - select an option from the dropdown.
  - In Repository user password - add the Basic authentication password, or add the PAT generated from your repository developer tools. Password must be entered directly when configuring the delivery method for these authentication methods.
- For SSH:
  - In Path to private key when using ssh - from the dropdown, select the file path to the remote repository RSA SSH private key generated using the old OpenSSH format.
  - In Repository ssh passphrase - add the remote repository SSH passphrase. The passphrase must be entered directly when configuring the delivery method.
On the Edit Delivery Configuration dialog, click the OK button to save the delivery method.