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.

A temporary local directory is used for SaaS environments and the following operations are performed:

Git clone
Git checkout (of configured branch)

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: Prior to configuration, dropdown parameters that rely on a property are empty. Hovering over the dropdown or clicking a dropdown displays the required property name to configure. To display the value(s), in the Self-Service UI, select the environment, and on the 'Configuration properties' tab, configure the property for your system. Refer to the Self-Service User Guide for information about setting configuration properties, including the use of the ${CUSTOMER_SECRETS_ROOT} and ${CUSTOMER_CONFIG_ROOT} variables.

Multiple entries can be added to the dropdown parameters using dynamic properties. Each configuration entry must have a unique integer or alpha identifier (indicated by [*]) as described below. When duplicate identifiers exist, only the last value is displayed in the dropdown.

Allow a few minutes for changes made in the Self-Service UI 'Configuration properties' tab to display in the workbench.

Configure data for the following dropdown parameters:

Configure the Remote git repository URI parameter using the GitDelivery.RemoteRepoUri.[*] property. For example:

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.
Configure the Git Branch parameter to define the name of the branch to which the delivery is published using the GitDelivery.Branch.[*] property. For example:
Configure the Repository username parameter using the GitDelivery.RemoteRepoUsername.[*] property. This property 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). For example:
Configure the Path to private key when using ssh parameter using the GetDelivery.SshPrivateKeyUri.[*] property. For example:

Configure SSH Connection
1. 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 uploaded via the Self-Service UI 'Configuration files' tab.
  
  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 (for example, 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.
Configure the Author name parameter using the GitDelivery.AuthorName.[*] property. For example:
Configure the Author email parameter using the GitDelivery.AuthorEmail.[*] property. For example:

Configuration

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

Note: The parameter dropdown options are defined by the properties outlined in the Prerequisites section above.

On the Configuration tab, in the Delivery Method area, click Edit Delivery.
In Select Delivery Method, choose Git Delivery.
In Local git repository URI, select no value, this is a legacy on-prem parameter.
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.