Plug-in Documentation

Git

Overview

The Git plug-in automates importing artifacts from a Git repository.

This plug-in includes one step which has no input properties:

The plug-in adds the following roles to resources:

Step palette

To access this plug-in in the palette, click Source and Repositories > Git.

Compatibility

This plug-in requires UrbanCode Deploy version 6.0 or later.

This plug-in supports all versions of the Git client.

This plug-in runs on all operating systems that UrbanCode Deploy supports, except the IBM z/OS operating system.

Installation

This plug-in is installed when installing IBM UrbanCode Deploy. When new plug-in versions are available, see Installing plug-ins in UrbanCode Products to update the plug-in.

History

Version 15

  • APAR PI89045: add support for setting isFinished flag when importing versions

Version 14

  • Fixes APAR PI87707, a regression where the user who requested a manual version import was not being tracked.

Version 13

  • Fixes APAR PI94103. Added an option to disable SSL certificate verification.

Version 12

  • Fixes APAR PI89187. Branch is now specified when making inital git clone command.
  • Branch property is now optional. Default value is master.
  • Improved error output when unable to identify Commit IDs or Tags.
  • If specified revision is not found, a hollow component version will no longer be created.

Version 11

  • RFE 110682. On default automatic imports where Watch for Tags is not specified, the plug-in will make a shallow copy of depth 1 to save time and space.
  • If a Version/Tag value or the Watch for Tags check box is specified, a full clone will be made.

Version 10

  • RFE 86753. Added support for Git submodules.

Version 9

  • Fixes APAR PI40551. Now uses working directory for temporary artifact storage.

Version 8

  • This release now encodes username to fix authentication issues.

Version 7

  • This release is being provided to include updated translations.

Version 6

  • Fixes APAR PI63702. Adds functionality to separate Includes and Excludes parameters with new lines or commas.

Version 5

  • Fixes APAR PI57417. Plug-in now checks the agent settings for acceptance of self signed certificates.

Version 4

  • Version 4 of this plug-in adds a setting to authenticate with a Git repository.

Troubleshooting

For more questions and answers about plug-ins, see the UrbanCode forum on IBM developerWorks.

Import process fails when using GitHub Enterprise

When using the Git source configuration plug-in with GitHub Enterprise, the import process can lock up or fail with the following error message:

Error Creating New Version: GIT error: Cloning into '{temp_dir}'...
fatal: unable to access 'https://{username}:****@{HTTPS_GitHub_Repo_Address}': Failed to connect to {enterprise_url} port 443: Connection refused

This error is caused by specifying an incorrect user name, password (access token), or GitHub repository address. The user name is the part of your email address before the at sign (@), and does not include the at sign or the domain name. The password is a personal access token that is generated in GitHub Enterprise. GitHub Enterprise requires the use of access tokens as a more secure login method.

To create a personal access token, complete the following steps.

  1. Log in to GitHub Enterprise, using your standard user name and password.
  2. Click your profile icon at the upper right of the page, and then click Settings.
  3. Click Personal access tokens on the left side of the window.
  4. Click Generate new token.
  5. Specify a name for the new token. Do not change the default scopes. Click Generate token.
  6. Copy and save the new token, which is a 40-character string.
  7. Use this personal access token as the Git source configuration password.

Note: To use this token with other deployments, you must save the token. If you do not save the token, you must follow the previous steps to generate a token again.

Settings

Process steps in the Git plug-in

Import Version

Import a new version from a Git repository.

This step has no input properties.

Roles in the Git plug-in

The plug-in adds these roles automatically to resources. You cannot add these roles
manually.

GitComponentProperties

Properties for the GitComponentProperties role
Name Type Description Property Reference
Branch String The Git branch that contains the artifacts you want to retrieve. The default is the
master branch.
${p:component/GitComponentProperties/branch}

Disable SSL Verification Boolean Disable SSL certificate verification. This option allows
invalid SSL certificates.
${p:component/GitComponentProperties/trustAllCerts}

Excludes String A list of file name patterns used to match files to be excluded. Use the double astrisk
(**) to include all directories and the single-astrick (*) to inlcude all
files. Separate each pattern with new lines or commas.
${p:component/GitComponentProperties/excludes}

Extensions of files to Convert String A list of file extension that must be converted into another character
set. Matching file extensions are converted into the default character set of the
system where the agent is located. Separate list items
commas.
${p:component/GitComponentProperties/extensions}

GIT Path String The path to the Git executable file on the UrbanCode Deploy server. If you have added
the Git executable to the system PATH variable, you can
specify the name of the executable, such as git. If you
have not added the Git executable to the system PATH variable,
specify the complete path to the Git executable.
${p:component/GitComponentProperties/gitPath}

Includes String A list of file name patterns used to match files to be included. Use the double astrisk
(**) to include all directories and the single-astrick (*) to inlcude all
files. For example, the pattern dist/**/*, retrieves the
entire file tree beneath the dist directory. Separate each pattern with new lines
or commas.
${p:component/GitComponentProperties/includes}

Password Password The password to authenticate with the Git repository when using the http(s) protocol. ${p:component/GitComponentProperties/password}

Preserve Execute Permissions Boolean For Linux and UNIX operating systems, select this property to retain the execute permissions
for each file.
${p:component/GitComponentProperties/saveFileExecuteBits}

Recursive Boolean Initialize all submodules within the project using their default settings. ${p:component/GitComponentProperties/recursive}

Repository URL String The location of the Git repository. For example: https://git.example.com/myproject.git. ${p:component/GitComponentProperties/repoUrl}

Username String The user name to authenticate with the Git repository when using the http(s) protocol. ${p:component/GitComponentProperties/username}

Watch for Tags Boolean Use tags as the basis for new component versions. ${p:component/GitComponentProperties/watchTags}

GitImportProperties

Properties for the GitImportProperties role
Name Type Description Property Reference
The version name to be created String
The version or tag String

Usage

Youll need to define an UrbanCode Deploy component which defines the source and processes for the Git repository. The component contains the information for importing the artifacts and any processes to implement on the artifacts.

When creating the component, youll supply information described on the Import Version step. After the component is created, use the Components page in the user interface to import a version of the artifacts if automatic import is not selected.

To create a component, complete the following steps. For more information about creating a component, see
Creating components in the product documentation.

  1. In UrbanCode Deploy, click Components and then click Create Component.
  2. In the Create Component window, specify a name and description for the component.
  3. In the Teams fields, specify the access information for the new component.
  4. To use a template for the new component, select a template from the Template list. In this case, the component inherits source configuration, properties, and processes from the template.
  5. In the Source Config Type list, select Git.
  6. Specify the properties for the component. See Settings for property descriptions. When referencing plug-in properties, you must specify the scope for the property. The scope is the type of artifact that contains the property, which for the Git plug-in is component. For example:

    ${p:component/GitComponentProperties/password}
  7. Click Save.

Import a version

When the artifacts are imported, a component version is created using the version of the package. You can specify to import a specific package version or import all versions. If importing all versions, a component version is created for each version.

  1. Click the Versions tab for the component.
  2. Click Import New Versions.
  3. Specify a specific version of the package to import, or leave blank to import the latest version of the package available in the repository. Additionally, enable Import All Versions to import all versions of a package.
  4. Click Save.