BMC AMI DevX Code Pipeline Operations template for GitLab CI/CD

This topic describes how to set up a GitLab Runner and run BMC AMI DevX Code Pipeline operations such as Generate, Promote, Deploy and Regress on the mainframe.

Prerequisites

To use this template, you need the following:

GitLab self-managed runner
BMC AMI Common Enterprise Services (CES).
BMC AMI DevX Workbench CLI installed on the same GitLab self-managed runner that you will be using.
BMC AMI DevX Code Pipeline Operations template for GitLab CI/CD:
- Windows: bmc-codepipeline-operations-windows.yml
- Linux: bmc-codepipeline-operations-linux.yml
BMC AMI DevX Code Pipeline example template for GitLab CI/CD .gitlab-ci.yml: example.yml
BMC AMI DevX Common Configuration GitLab CI/CD template: bmc-common-config.yml
(For Linux only), Install jq

To set up GitLab Runner

Go to GitLab Runner, select the operating system used on your system infrastructure, and follow the steps in that procedure.

Important

The BMC AMI DevX Code Pipeline Operations template supports runners for Windows and Linux only.

Alternatively, you can set up GitLab Runner by performing the following steps:

On the GitLab home page, select Project in the Your Work pane.
Select Settings > (letter-spacing:0px" %)CI/CD.
(letter-spacing:0px" %)On the CI/CD page, select Runner > Expand > New Project Runner and follow the instructions on the page.
After installing GitLab Runner and registering the runner, the runner is displayed in the(letter-spacing:0px" %) Assigned Project Runners section.

To use the Code Pipeline Operations template for GitLab CI/CD in your pipeline

Download the following templates to your root directory:

Template	Source location
BMC AMI DevX Code Pipeline Operations template	bmc-codepipeline-operations-windows.yml bmc-codepipeline-operations-linux.yml
BMC AMI DevX Common Configuration template	bmc-common-config.yml

The Code Pipeline Operations template for Gitlab CI/CD depends on the BMC AMI DevX Common Configuration GitLab CI/CD template to provide configuration options.

On the GitLab home page in the Your Work pane, select Settings>CI/CD.
On the CI/CD page, select Variable > Expand > Add Variable.

In the Add Variable dialoge box:
1. In the Key field, enter HOST_CONNECTIONS. For more information about HOST_CONNECTIONS, see bmc-common-config.yml.
2. In the Value field, enter a value. A sample variable is as follows:
  {
  "hostconnections": [
  {
  "host": "cw09.bmc.com:47623",
  "description": "TPZP",
  "protocol": "NONE",
  "code_page": "1047 - Latin 1 (Open Systems)",
  "timeout": "30",
  "ces_url": "http://cw01.bmc.com:2020"
  },
  {
  "host": "cw09.bmc.com:47624",
  "description": "TPTP",
  "protocol": "NONE",
  "code_page": "1047 - Latin 1 (Open Systems)",
  "timeout": "30",
  "ces_url": "http://cw01.bmc.com:2020"
  }
  ],
  "windows_CLI": "C:\\Topaz-CLI-installed-versions\\TopazCLI-GA-20.14.03",
  "linux_CLI": "/home/gitlab-runner/TopazCLI-GA-20.14.03"
  }
3. In the Type field, select File from the list.

Key considerations

To use the BMC AMI DevX Code Pipeline operation in your job:

Add the BMC AMI DevX Code Pipeline Operations template to an existing `.gitlab-ci.yml` file by using the include keyword. See example.yml.
include:
local: bmc-codepipeline-operations-windows.yml
To use BMC AMI DevX Code Pipeline Operations template in your job, extend the predefined job templates depending on the operation that you want to perform, as described in the following table:

	OS/Runner	Predefined template job	Variables to pass (mandatory)	Variables to pass (optional)
Add a task to an assignment	Windows	.add_a_task_to_an_assignment	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ASSIGNMENT_ID: Specifies the container id. CHECKOUT: Specifies whether to check out the task. Valid values are true and false. The default value is false. REQ_BODY: Specifies the data (AddTaskInfo) used to create the task in the assignment. For more information, see Code-Pipeline-REST-API.	None
Add a task to an assignment	Linux	.add_a_task_to_an_assignment_linux		None
Promote an assignment or release	Windows	.promote_an_assignment / .promote_release	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ASSIGNMENT_ID or RELEASE_ID: Specifies the container id. LEVEL: Specifies that the tasks in the container at this level will be promoted or will require a check out. Valid values are true and false. Default value is false.	MTYPE: Promotes component of this type in the container. MNAME: Promotes components with this name in the container. REQ_BODY: Specifies the data (SetInfo) used to perform a promote operation. For more information, seeCode-Pipeline-REST-API.
Promote an assignment or release	Linux	.promote_an_assignment_linux / .promote_release_linux
Regress an assignment or release	Windows	.regress_an_assignment/ .regress_release	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ASSIGNMENT_ID or RELEASE_ID: Specifies the container id. LEVEL: Specifies that the tasks in the container at this level will be regressed. Default value is false.	MTYPE: Specifies the components type in the container that will be regressed. MNAME: Specifies the components name in the container that will be regressed. REQ_BODY: Specifies the data (SetInfo) used to perform a promote operation. For more information, see Code-Pipeline-REST-API.
Regress an assignment or release	Linux	.regress_an_assignment_linux / .regress_release_linux
Generate tasks In assignment / generate tasks In release	Windows	.generate_an_assignment/ .generate_release	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ASSIGNMENT_ID or RELEASE_ID: Specifies the container id. LEVEL: Specifies that the tasks in the container at this level will be generated. Valid values are true and false. Default value is false.	MTYPE: Specifies the components type in the container that will be generated. MNAME: Specifies the components name in the container that will be generated. REQ_BODY: Specifies the data (SetInfo) used to perform a promote operation. For more information, see Code-Pipeline-REST-API.
Generate tasks In assignment / generate tasks In release	Linux	.generate_an_assignment_linux/ .generate_release_linux
Generate task	Windows	.generate_tasks	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ASSIGNMENT_ID: Specifies the container id. LEVEL: Specifies that the tasks in the container at this level will be generated. Valid values are true and false. Default value is false.	REQ_BODY: Specifies the data (SetInfo) used to perform a promote operation. For more information, see Code-Pipeline-REST-API.
Generate task	Linux	.generate_tasks_linux
Build an assignment	Windows	.build_an_assignment	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ASSIGNMENT_ID: Specifies the container id. LEVEL: Specifies the task level to be built. Valid values are true and false. Default value is false.	MTYPE: Specifies the components type in the container to be built. MNAME: Specifies the components name in the container to be built. REQ_BODY: Specifies the data (SetInfo) used to perform a promote operation. For more information, see Code-Pipeline-REST-API.
Build an assignment	Linux	.build_an_assignment_linux
Build release	Windows	.build_release	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. RELEASE_ID: Specifies the release id. ASSIGNMENT_ID: Specifies the container id. LEVEL: Specifies the task level to be built. Valid values are true and false. Default value is false.	MTYPE: Specifies the components type in the container to be built. MNAME: Specifies the components name in the container to be built. REQ_BODY: Specifies the data (SetInfo) used to perform a promote operation. For more information, see Code-Pipeline-REST-API.
Build release	Linux	.build_release_linux
Build task	Windows	.build_tasks	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. APPLICATION: The application name. LEVEL: Specifies the task level to be built. Valid values are true and false. Default value is false. MTYPE: Specifies the components type in the container to be built. MNAME: Specifies the components name in the container to be built.	ASSIGNMENT_ID: Specifies the container id. SUBAPPL: Specifies the sub application name. REQ_BODY: Specifies the data (SetInfo) used to perform a promote operation. For more information, see Code-Pipeline-REST-API.
Build task	Linux	.build_tasks_linux
Get assignment / release info	Windows	.assignment_info / .release_info	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ASSIGNMENT_ID or RELEASE_ID: Specifies the container id.	None
Get assignment / release info	Linux	.assignment_info_linux / .release_info_linux		None
Get release task info	Windows	.release_task_info	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. RELEASE_ID: Specifies the release id. TASK_ID: Specifies the task id.	None
Get release task info	Linux	.release_task_info_linux		None
Get assignment / Release task list	Windows	.assignment_task_list / .release_task_list	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ASSIGNMENT_ID or RELEASE_ID: Specifies the container id. LEVEL: Specifies the task level to be built.	None
Get assignment / Release task list	Linux	.assignment_task_list_linux / .release_task_list_linux		None
Get set info	Windows	.set_info	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. SET_ID: Specifies the container id. LEVEL: Specifies the task level to be displayed.	None
Get set info	Linux	.set_info_linux		None
Get set task list	Windows	.set_task_list	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. SET_ID: Specifies the container id.	None
Get set task list	Linux	.set_task_list_linux		None
Get container list	Windows	.get_container_list	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token.	USER_ID: Specifies the owner or joined user for the container. CONTAINER_ID: It is same as the Assignment id, Release id or Set id. Trailing wildcards are supported, that is, PRFX0000* CONTAINER_TYPE: Specifies the container type. The valid types are: A=Assignment R=Release S=Set APPLICATION: Specifies the Code Pipeline application id. Trailing wildcards are supported, such as FOO* SUBAPPL: Specifies the sub application. Trailing wildcards are supported, such as FOO* OWNER: Specifies the container owner. Trailing wildcards are supported such as MYID. DESCRIPTION: Specifies the container. Trailing wildcards are supported such as REF123. REF_NUMBERSpecifies the site defined number used to associate the container with a problem ticket number or change request number. Trailing wildcards are supported such as MYISSUE* RELEASE_ID: Refers to the 10-character release number, if associated with an assignment. Trailing wildcards are supported, such as, RELEASE1. STREAM: Specifies the Code Pipeline stream name. Trailing wildcards are supported such as BAR TAG: Specifies the user-definable four-character field. Trailing wildcards are supported, such as TAG* (Case sensitive) INCLUDE_CLOSED_CONTAINERS: Specifies if the closed container in the list needs to be included. Valid values are true or false.
Get container list	Linux	.get_container_list_linux
Get release task generate listing	Windows	.release_task_generate_listing	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. RELEASE_ID: Specifies the container id. TASK_ID: Specifies the task id.	None
Get release task generate listing	Linux	.release_task_generate_listing_linux		None
Get work list	Windows	.get_worklist	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token.	OWNER: Specifies the container owner who performed the checkout operation. APPLICATION: Specifies the container's primary application code. Containers may include components from multiple applications. Trailing wildcards are supported such as, FOO* SUBAPPL: Specifies the primary sub application. Containers may include components from multiple applications. Trailing wildcards are supported, such as FOO. TYPE: Specifies the 1–4-character acronym for the type of component, such as COB for a Cobol program or COPY for a copybook. Trailing wildcards are supported such as, C NAME: Refers to the case sensitive component name. Trailing wildcards are supported such as, TPROG* START_DATE: Specifies the start date in yyyy-mm-dd format to filter a range based on last update. END_DATE: Specifies the end date in yyyy-mm-dd format to filter a range based on last update. OPERATION: Specifies the last operation performed on this component. Valid operation values are Browse, Checkout, Delete, Edit, Fallback, Generate, Implement, Loaded, Promote, Regress, Transfer, and Update Replace Version. LEVEL: Specifies the level of this component when the last operation was requested. Trailing wildcards are supported such as, DEV. ENVIRONMENT: Specifies the Code Pipeline environment for this version, OUTS, TEST, HOLD, or PROD. Trailing wildcards are supported such as, PRO STREAM: Specifies the 2- to 8-character code that defines the application structure with which the application is associated. Trailing wildcards are supported such as, BAR* LAST_UPDATED_BY: Specifies the User ID that requested the last significant operation. RELEASE_ID: Specifies the Release id a component belongs to. Trailing wildcards are supported such as, RELEASE1* REF_NUMBER: Specifies the site defined number used to associate the container with a problem ticket number or change request number. Trailing wildcards are supported such as MYISSUE* GROUP: Specifies a component or a task belonging to this owner application group. Trailing wildcards are supported such as, FOO* IN_PROGRESS: Specifies whether to include active tasks that are not in Production. Valid values are true or false. The default value is true. PRODUCTION: Specifies whether to include current Production tasks. Valid values are true or false. The default value is false. HISTORICAL: Specifies whether to include old Production tasks. Valid values are true or false. The default value is false.
Get work list	Linux	.get_worklist_linux
Cancel assignment	Windows	.cancel_assignment	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ASSIGNMENT_ID: Specifies the container id to be cancelled.	None
Cancel assignment	Linux	.cancel_assignment_linux		None
Cancel deployment	Windows	.cancel_deployment	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token.	REQUEST_ID: Specifies the request id of the deployment to be cancelled.
Cancel deployment	Linux	.cancel_deployment_linux
Cancel release	Windows	.cancel_release	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. RELEASE_ID: Specifies the release id to be cancelled.	None
Cancel release	Linux	.cancel_release_linux		None
Close assignment	Windows	.close_assignment	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ASSIGNMENT_ID: Specifies the container id that to be closed.	None
Close assignment	Linux	.close_assignment_linux		None
Close release	Windows	.close_release	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. RELEASE_ID: Specifies the release id to be closed.	None
Close release	Linux	.close_release_linux		None
Create assignment	Windows	.create_assignment	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. REQ_BODY: Specifies the data used to create an Assignment Container. For more information, see Code-Pipeline-REST-API.	None
Create assignment	Linux	.create_assignment_linux		None
Create release	Windows	.create_release	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. REQ_BODY: Specifies the data used to create an Assignment Container. For more information, see Code-Pipeline-REST-API.	None
Create release	Linux	.create_release_linux		None
Deploy assignment	Windows	.deploy_assignment	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ASSIGNMENT_ID: Specifies the container id. LEVEL: Specifies the tasks in the assignment that will be deployed. TYPE: Specifies the component in the assignment to be deployed. NAME: Specifies the component name in the assignment to be deployed. REQ_BODY: Specifies the data (DeployInfo) used to perform a deploy operation. For more information, see Code-Pipeline-REST-API.	None
Deploy assignment	Linux	.deploy_assignment_linux		None
Deploy release	Windows	.deploy_release	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. RELEASE_ID: Specifies the release id to be deployed. LEVEL: Specifies the tasks in the assignment that will be deployed. TYPE: Specifies the component in the assignment to be deployed. NAME: Specifies the component name in the assignment to be deployed. REQ_BODY: Specifies the data (DeployInfo) used to perform a deploy operation. For more information, see Code-Pipeline-REST-API.	None
Deploy release	Linux	.deploy_release_linux		None
Deploy task	Windows	.deploy_tasks	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ASSIGNMENT_ID: Specifies the container id. LEVEL: Specifies the tasks in the assignment that will be deployed. REQ_BODY: Specifies the data (DeployInfo) used to perform a deploy operation. For more information, see Code-Pipeline-REST-API.	None
Deploy task	Linux	.deploy_tasks_linux		None
Fallback assignment	Windows	.FallbackAssignment	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ASSIGNMENT_ID: Specifies the container id. LEVEL: Specifies the tasks in the assignment that will be deployed. MTYPE: Specifies the component type in the assignment for fallback operation. MNAME: Specifies the component name in the assignment for fallback operation.	REQ_BODY: Specifies the data (DeployInfo) used to perform a fallback operation. For more information, see Code-Pipeline-REST-API.
Fallback assignment	Linux	.FallbackAssignment_linux
Fallback release	Windows	.FallbackRelease	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. RELEASE_ID: Specifies the container id. LEVEL: Specifies the tasks in the assignment that will be deployed. MTYPE: Specifies the component type in the assignment for fallback operation. MNAME: Specifies the component name in the assignment for fallback operation.	REQ_BODY: Specifies the data used to perform a fallback release operation. For more information, see Code-Pipeline-REST-API.
Fallback release	Linux	.FallbackRelease_linux
Remove from release	Windows	.RemoveFromRelease	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ASSIGNMENT_ID or RELEASE_ID: Specifies the container id. LEVEL: Specifies the tasks in the container to be removed. MTYPE: Specifies the component type to be removed. MNAME: Specifies the components name to be removed. TASK_ID: Specifies the task ID you want to remove.	None
Remove from release	Linux	.RemoveFromRelease_linux		None
Set operation	Windows	.SetOperation	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. SETID: Specifies the set ID you want to perform the action on. SET_ACTION: Specifies the action to be performed on the set. Valid actions are hold, release, lock, unlock, delete, restart, close and terminate or approve, deny and reset. APPROVER: Specifies the approver role. It is only applicable to the approve, deny, and reset actions. REQ_BODY: Specifies the data used to perform a promote operation. For more information, see Code-Pipeline-REST-API.	None
Set operation	Linux	.SetOperation_linux		None
Task load	Windows	.TaskLoad	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ASSIGNMENT_ID or RELEASE_ID: Specifies the container ID. REQ_BODY: Specifies the data (SetInfo) used to perform a promote operation. For more information, see Code-Pipeline-REST-API.	None
Task load	Linux	.TaskLoad_linux		None
Transfer task	Windows	.TransferTask	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ASSIGNMENT_ID or RELEASE_ID: Specifies the container ID. LEVEL: Specifies the tasks in the container to be promoted. Valid values are true or false. Default value is false. MTYPE: Specifies the component type to be promoted. MNAME: Specifies the components name to be promoted. TASK_ID: Specifies the task ID you want to transfer. REQ_BODY: Specifies the data (SetInfo) used to perform a promote operation. For more information, see Code-Pipeline-REST-API.	None
Transfer task	Linux	.TransferTask_linux		None
Deploy list	Windows	.DeployList	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. ENVIRONMENT: Specifies the logical run environment where the components will be deployed for the request. This field is not case sensitive. only Wildcard * is supported. STATUS: Specifies the overall current status of the deploy request, which may be Planned, Confirmed, Staged, Implemented, Completed, Failed, or Terminated. This field is not case sensitive. Only Wildcard * is supported. TODAYS_DATE: It is a True or false value indicating whether or not to include today's date deployments. PRIOR_WEEK: It is True or false value indicating whether or not to include prior week's deployments.	START_DATE: Specifies the deployment start date/time in yyyy-mm-dd format for the set to be dispatched. END_DATE : Specifies the deployment end date/time in yyyy-mm-dd format. REQUEST_ID: Specifies a unique numerical id assigned to the deployment request. SETID: Specifies the set IDyou want the information about. This field is case sensitive. Only Wildcard * is supported.
Deploy list	Linux	.DeployList_linux
Git to ispw sync	Windows	.git_to_ispw_sync	SELECTED_HOSTNAME: Specifies the HOST_CONNECTIONS variable to select a unique host connection. CES_TOKEN: Specifies the CES token. USER_ID: Specifies the username. USER_PASSWORD: Specifies the user password. CODEPIPELINE_RUNTIME_CONFIGURATION: Specifies the Code Pipleline server configuration. CODEPIPELINE_APPLICATION: Specifies the Code Pipeline application. CODEPIPELINE_STREAM: Specifies the Code Pipleline stream. CHECKOUT_LEVEL: Specifies the test level to check out component.	CODEPIPELINE_SUBAPPLICATION: The ISPW subapplication. CONTAINER_CREATION: Specifies the option to create a new Code Pipeline container. BUILD_AUTOMATICALLY: Specifies a case sensitive variable indicating whether to build the tasks loaded during sync operation. It reads the output from automaticBuildParams.txt and issues a build call for all tasks in given assignment. ISPWCONFIG_PATH: Specifies the path to ispwconfig.yml.
	Linux	.git_to_ispw_sync_linux
	Linux	.git_to_ispw_sync_linux	Warning Important For linux git-to-ispw-sync operation, make sure that the user or service gitlab-runner you are using to run the pipeline, has the permissions to access TopazCLI installation directory.