Registering and updating Git repositories by using scripts

As an alternative to using the web client, you can download and run scripts to register, update, and retrieve information about Git repositories. Scripts are particularly helpful when you need to register multiple repositories.
To use these scripts, use a Node.js server (Version 6.11.0 or later) and complete these steps.
  1. Download the Git Integration Toolkit from https://jazz.net/downloads/workflow-management/releases/version/Git-Server-Toolkit-version.zip. Extract the .zip file.
  2. Navigate to the Git-Server-Toolkit-version/rtcgit-admin-scripts folder and run the npm install command.
Tip: The README.txt file in the Git-Server-Toolkit-version/rtcgit-admin-scripts folder has several examples of using the scripts.

Logging

Before you run a script, set the environment variable RTC_GIT_SCRIPTS_TRACE_LEVEL to a value between 1 and 4 to enable logging.

On Windows: set RTC_GIT_SCRIPTS_TRACE_LEVEL=value

On Linux: export RTC_GIT_SCRIPTS_TRACE_LEVEL=value

Table 1. Logging values
Value Logging level
0 No logging.
1 Errors
2 Warnings
3 Informational
4 Verbose

To trace requests and responses made and received by the command-line interface to and from the IBM® Engineering Workflow Management (EWM) server, set the environment variable RTC_GIT_SCRIPTS_HTTP_TRACING to true before you run the scripts. You must also have the RTC_GIT_SCRIPTS_TRACE_LEVEL environment variable set to the value 4; otherwise, no output is produced.

On Windows: set RTC_GIT_SCRIPTS_HTTP_TRACING=true

On Linux: export RTC_GIT_SCRIPTS_HTTP_TRACING=true

Setting the display language

To interact with the scripts in a language other than the default, English, set the environment variable RTC_GIT_SCRIPTS_LANG. Acceptable values are:
  • cs
  • de
  • en
  • fr
  • hu
  • it
  • ja
  • ko
  • pl
  • pt_Br
  • ru
  • tr
  • zh
  • zh_HK
  • zh_TW

Execution

Navigate to the Git-Server-Toolkit-version/rtcgit-admin-scripts folder. Run a script by using the following syntax: node script-name.js parameter1:"value" parameter2:"value" .... To view usage information about a script, include the ―help argument. Example: node RegisterGitRepository.js ―help.

Note:

Command parameters enclosed within brackets, [ ], are optional.

Note:
Use double quotes around parameter values that follow a colon (:). For a complex value like refMapping, use single quotes around all the fields in the value. For example:
refMappings:”[{‘name’:’test_name’,’processArea’:’test’,’desc’:'test2desc'},{'name':'test2name','processArea': 'test2'}]"

To view version information of the scripts, open the VERSION file in the Git-Server-Toolkit-version/info directory. You can also run any script with the ―version argument to view the version information.

RegisterGitRepository.js

Use this script to register Git repositories.

Table 2. Parameters for RegisterGitRepository.js
Parameter Description
hostUrl URL of the EWM server. Example: https://host-name:9443/ccm.
userId Login user ID.
password Login password.
prompt Prompt for password. Valid values are true and false.
projectareaName Name of the project area under which this Git repository should be registered.
repoName Name of the Git repository.
description Description of the Git repository.
url URL for the Git repository.
hostingServer Git Repository Hosting Server. Valid values are NONE, GITHUB, GITLAB, GITHUB_ENTERPRISE. Use NONE for Apache and Node.js hosting servers.
secretKey The secret key used in the GitHub, GitHub Enterprise and GitLab integration’s webhook configuration.
ownerPresent Indicates whether EWM process should be applied to operations on this Git repository.

Example: node RegisterGitRepository.js hostUrl: "https://localhost:9443/ccm" userId:"clm" prompt:"true" projectareaName:"demo" repoName:"poc" url:"https://localhost:9999/git/poc.git" description:"This repository used for poc development"

UpdateGitRepository.js

Use this script to make modifications to a Git repository.

Table 3. Parameters for UpdateGitRepository.js
Parameter Description
searchUrl URL of the registered Git repository to update.
hostUrl URL of the EWM server. Example: https://host-name:9443/ccm.
userId Login user ID.
password Login password.
projectareaName Name of the project area.
prompt Prompt for password. Valid values are true and false.
repoName Name of the Git repository. Provide a new value to update the name of the registered Git repository.
description Description of the Git repository.
url New URL for the Git repository.
hostingServer Git Repository Hosting Server. Valid values are NONE, GITHUB, GITLAB, GITHUB_ENTERPRISE. Use NONE for Apache and Node.js hosting servers.
secretKey The secret key used in the GitHub, GitHub Enterprise and GitLab integration’s webhook configuration.
ownerName The name of the team area that should be the process owner for this Git repository.
ownerPresent Indicates whether EWM process should be applied to operations on this Git repository.
commitUriFormat Commit URI format: $repo/commit/$sha1 where $repo identifies the Git repository URL, and $sha1 identifies the commit ID.
userBranchPrefix Prefix for identifying user branches in the Git repository
refMappings Mapping from Git Repository branches to EWM team area names.
deleteRefMappings A comma-separated list of Git repository branch names. The mappings for these Git repository branches will be removed.

Example: node UpdateGitRepository.js hostUrl: "https://localhost:9443/ccm" userId:"clm" prompt:"true" searchUrl:"https://localhost/git/demo.git" commitUriFormat:"$repo/commit/$sha1" userBranchPrefix:"refs/branch/$user/" refMappings: "[{'name':'test_name','processArea': 'demo/test', 'desc': 'test2desc'},{'name': 'test2name', 'processArea":"demo/test2'}]" hostingServer:”GITHUB_ENTERPRISE” secretKey:”demokey”

GetGitRepository.js

Use this script to retrieve information about a Git repository.

Table 4. Parameters for GetGitRepository.js
Parameter Description
searchUrl URL of the registered Git repository to retrieve. You must specify the searchUrl parameter or the processArea parameter. If you specify both parameters, only those repositories that match the searchUrl value and are owned by the processArea value are retrieved.
hostUrl URL of the EWM server. Example: https://host-name:9443/ccm.
userId Login user ID.
password Login password.
processArea Name of a project area or team area specified within quotes. Specify the team area as “project area name/team area name”. The script retrieves Git repositories that are registered to this project area or are owned by the team area. If you specify both the processArea parameter and the searchUrl parameter, the script retrieves only those Git repositories that match the searchUrl value and are owned by the processArea value.
prompt Prompt for password. Valid values are true and false.
showDetails Output details about the registered Git repository. By default, the command produces a condensed output. Valid values are true and false. Default value is false.
Example:
node GetGitRepository.js hostUrl: "https://localhost:9443/ccm" userId:"clm" prompt:"true" searchUrl:"https://localhost:9999/git/poc.git"
Example:
#To retrieve all Git repositories registered in the project area
node GetGitRepository.js hostUrl: "https://localhost:9443/ccm" userId:"clm" prompt:"true" processArea:”DemoProjectArea”
Example:
#To retrieve all Git repositories owned by the team area
node GetGitRepository.js hostUrl: "https://localhost:9443/ccm" userId:"clm" prompt:"true" processArea:”DemoProjectArea/DemoTeamArea”
Example:
#To retrieve all Git repositories registered in the project area starting with the URL prefix
node GetGitRepository.js hostUrl: "https://localhost:9443/ccm" userId:"clm" prompt:"true" processArea:”DemoProjectArea” searchUrl:”https://localhost:9999/git”

DeleteGitRepository.js

Use this script to delete the registration of Git repository in EWM.

Table 5. Parameters for DeleteGitRepository.js
Parameter Description
searchUrl URL of the registered Git repository to delete.
hostUrl URL of the EWM server. Example: https://host-name:9443/ccm.
userId Login user ID.
password Login password.
prompt Prompt for password. Valid values are true and false.

Example: node DeleteGitRepository.js hostUrl: "https://localhost:9443/ccm" userId:"clm" prompt:"true" searchUrl:"https://localhost:9999/git/poc.git"


video icon Video

Jazz.net channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community

Jazz.net
Jazz.net forums
Jazz.net library

support icon Support

IBM Support Community
Deployment wiki