Detailed Steps

Set up the environment

To set up the environment, you will:

1. Install the necessary plugins in Workbench for Eclipse.
2. Configure GitHub Self-hosted Runner
3. Complete Extra Setup for Code Pipeline Synchronization

Install the necessary plugins in Workbench for Eclipse

Install Egit: Refer to https://www.eclipse.org/egit/download/ for the installation.

Configure GitHub self-hosted runner

This how-to will guide you on the setup required for creating a self-hosted runner and some configurations to get you started.

Step-by-step Guide to Create the self-hosted runner

Before starting, ensure you know what machine/environment you would like to create the self-hosted runner. In some cases, you would want this installed on a virtual machine, and in other cases on your own machine. It's also important to understand the difference between all 3 levels that a self-hosted runner can be set-up on. See the explanation below to better understand the 3 levels and which one is more applicable for you.

• Repository-level runners are dedicated to a single repository.
• Organization-level runners can process jobs for multiple repositories in an organization.
• Enterprise-level runners can be assigned to multiple organizations in an enterprise account.

The steps below will be more geared towards creating a repository/organization level self-hosted runner with one pre-requisite, that you have a machine, whether it's a VM or your own machine ready to host a self-hosted runner.

1. Create the necessary environment before we run the steps for creating a self-hosted runner.

   • 
     
     • For an organization-level self-hosted runner, now is the time to create an organization if one does not already exist.
     • For a repository-level self-hosted runner, create a new repository through GitHub, or you may simply use an existing repository if you already have one created.

   Warning

   Important

   Only create private repositories when working with self-hosted runners. You do not want public access to your privately self-hosted machines.

2. In GitHub, navigate to the settings page that will allow you to create a self-hosted runner. You can find this page by going into the settings of your organization/repository and clicking on the Actions menu option within the settings.
3. Go to the bottom of the page and find the Self-hosted runners section (or may see "Runners" under the Actions menu). From there, select the Add new option → New runner for an Organization and New runner for a Repository.
   
4. You will be redirected to a new page that will outline the steps for creating a runner. Within that page, prior to running any of those steps, you will need to select the Operating System of the machine on which you will host the runner from. The steps described below will be for a Windows VM, but the steps are similar to any other OS.

5. Run the commands/steps provided on that page. Keep in mind that the token within the Configure section of that instructions page expires and the page will need to be refreshed to retrieve a new token if the old one has expired.

   You will need to use your shell to run the commands. Use the correct shell for your OS. In order for the service to execute, the PowerShell has to be started with the run as administrator option within Windows. You may need to download PowerShell for Windows from Github (run the .msi in Github from https://github.com/PowerShell/PowerShell/releases/tag/v7.1.3) or bash shell for Linux. When asked if you want the runner to run as a service, We recommend you indicate Yes, so it does not need to be manually started each time you want to use it. Else go to the actions-runner location and execute the run.cmd.

   You can also provide labels for your runner while running the GitHub instructions in the shell window. Towards the beginning of the runner installation, a step will ask you the following:
   This runner will have the following labels...
   Enter any additional labels

   At this point, you can enter any labels you prefer to associate to this runner. Labels can be used to run specific runners by their label during an action execution. You can also change the labels after installing the runner. To change them through GitHub, follow the steps which can be found here.

6. After running the steps within your shell, the shell should look something like this
   
7. To double-check that the runner installed successfully, for a Windows machine once the process is completed, you can go into your services (not from task manager, but rather open your start menu and search for services) and look for GitHub Actions Runner. If you see that, then that means the process completed successfully and that your runner is currently running.
   

Complete extra setup for Code Pipeline synchronization

Extra setup steps are required for Code Pipeline Synchronization when using:

• ispw-sync GitHub Docker action
• ispw-sync-local GitHub action

Setup if using the ispw-sync GitHub Docker action

In order to use ispw-sync Docker container action (a TopazCLI Docker image is distributed from Docker hub and no need to install TopazCLI on the self-hosted runner), self-hosted runner must use a Linux operating system and have Docker installed. Currently, GitHub only supports Linux self-hosted runner for Docker container action.

Assume an Ubuntu based self-hosted runner is preferred, run the following commands to install Docker.

Because the action-runner cannot run under root, so the action-runner will have the following error to trigger an antion of any docker action:

To resole the issue, modify the permission and restart Docker daemon:

Setup if using the ispw-sync-local GitHub action

If Windows based self-hosted runner, install the TopazCLI windows distribution.

If Linux based self-hosted runner, install the TopazCLI Linux distribution.

Please remember the root path to TopazCLI, then specify the CLI location in the ispw-sync-local action.

Verify the Code Pipeline mainframe PLAY application is available

Verify that the Code Pipeline PLAY application is installed. It should be included as part of the Training Application delivered in the Code Pipeline SAMPLIB as part of the Installation Verification Process (IVP).

If the following steps can be executed successfully, then the PLAY application was successfully installed in the Code Pipeline instance based on the host connection.

If you are unable to locate the PLAY application, refer to the Code Pipeline Installation and Configuration Guide section entitled Installation Verification Procedures, which includes information on installing the Code Pipeline mainframe PLAY application. The Code Pipeline Installation and Configuration Guide can be found at BMC Support Central.

1. In Workbench for Eclipse, open the Code Pipeline perspective. From the Window menu, select Open Perspective>Other. The Open Perspective dialog box appears. Select Code Pipeline and click OK. The Code PipelineRepository Explorer view appears.

   Warning

   Important

   The Code Pipeline Repository Explorer view is visible by default. If it is not visible, from the Window menu, select Show View>Other. The Show View dialog box appears. Toggle open Code Pipeline, select the Code PipelineRepository Explorer view, and click OK.

2. Perform the following actions:
   • From the Stream list, select PLAY.
   • From the Application list, select PLAY.
   • From the Level list, select DEV1.
   • From the Level option list, select First found in level and above.

3. Click Apply. A filtered list of the components within the PLAY application appears.

   Success

   Tip

   If you are not logged into a host connection where the Code Pipeline PLAY application is installed, you will be prompted when you select any list in the Code Pipeline Repository Explorer view.

Set up a GitHub repository with the Code Pipeline source and YAML configuration file

To create a new GitHub repository named GitPlay, perform the following steps:

1. Go to the GitHub.
2. To create a personal repository, select Your repositories from profile, then select New.
   
3. Make sure Add a README file is checked, so the repository is fully initialized.
   

Clone GitPlay repository from GitHub and import as an Eclipse project

1. In Workbench for Eclipse, open the Git perspective.
2. Clone the GitPlay repository.
   
3. Import the repository as standard Eclipse project once the repository is cloned successfully,
   

Configure Code Pipeline and import the Code Pipeline source

1. In Workbench for Eclipse’s Project Explorer view, right-click the GitPlay project node and select Configure>Configure to Use 

   Code Pipeline

   . The Configure 

   Code Pipeline

   and GIT Mapping wizard appears.

2. From the Host list, select the host where the PLAY application is located, or click Configure to configure a host. We recommend using the fully qualified domain name when configuring the host.
3. In the Runtime Configuration field, enter the runtime configuration if not using the default Code Pipelineinstance.
4. Click Next. The next page of the wizard appears.
5. From the Stream list, select PLAY.
6. From the Application list, select PLAY.
7. From the Level list, select the level used when doing a build.
8. From the Download source from path list, choose the level from which to download source for the project.
9. In the YAML mapping file location field, enter or browse to the project folder in which to create the YAML mapping file. By default, the location is the root of project.
10. Click Finish. The source is downloaded. The ispwconfig.yml file is created and added to the root of the GitPlay project in the Project Explorer view. The Console view shows the activity and the Project Explorer view shows the downloaded files.
    
    
    

11. To examine the contents of the ispwconfig.yml file, right-click the file and select Open.

    !!com.compuware.ispw.cli.model.IspwRoot
       ispwApplication:
       application: PLAY
      host: somehost.example.com
       pathMappings:
      - path: \CLST
       types:
      - fileExtension: clst
       ispwType: CLST
         - path: \COB
       types:
      - fileExtension: cob
       ispwType: COB
         - path: \COPY
       types:
      - fileExtension: copy
       ispwType: COPY
         - path: \JOB
       types:
      - fileExtension: job
       ispwType: JOB
          port: 12345
          runtimeConfig: TPZP
          stream: PLAY

12. Refer to the 

    Code Pipeline

    to GIT Integration: 

    Code Pipeline

    YAML Configuration File for information on the available Code Pipelineproperty settings and path mappings that can be in the ispwconfig.yml file.

Commit and Push the initial source into the GitPlay Repository

1. In Workbench for Eclipse, open the Git perspective.
2. If the Git Staging view is not visible, from the Window menu, select Show View>Other. The Show View dialog box appears. Select Git>Git Staging, and click Open.
3. If there is no repository selected in the Git Staging view, click and select GitPlay to switch to the GitPlay repository.
4. In the Unstaged Changes box, select all of the components and click  to add them to the Staged Changes box.
   
5. In the Commit Message box, enter a commit message, such as Commit to main.
6. Click Commit and Push.

Create a GitHub Workflow

1. In Project Explorer View, select Filters and Customization..., then uncheck .*resources to show hidden files and folders for the GitPlay project.
   
   
   

1. Expand GitPlay project, create folder .github/workflows.
2. Create a GitHub workflow file, for example, ispw-sync-build-deploy.yml (Download a template), the workflow is broken up into the following stages:
   
   • Checkout - checks out the source code.
   • Synchronize changeset to Code Pipeline - uses GitHub action ispw-sync to perform GitHub to Code Pipeline synchronization.
   • Build Code Pipeline tasks - uses GitHub action ispw-build to perform a build

   • Deploy Code Pipeline tasks - uses gitHub action ispw-deploy to perform a deploy
     
     
     

     Success

     Tip

     To better understand how variable substitutions work in the workflow file, see Environment variables.

3. Or if you prefer to use GitHub action ispw-sync-local, you may specify the sync step as below, the workflow is broken up into the following stages (Download a template - ispw-sync-local-generate-deploy.yml):

   • Checkout - checks out the source code.
   • Synchronize changeset to Code Pipeline - uses GitHub action ispw-sync-local to perform GitHub to Code Pipeline synchronization.
   • Generate Code Pipeline tasks - uses GitHub action ispw-generate to perform a generate.
   • Deploy Code Pipeline tasks - uses GitHub action ispw-deploy to perform a deploy.
     
     
     
4. Create secrets to hide usernames, passwords, or tokens that will be used in the workflows
   
   1. Navigate to your GitHub repository where your workflows are stored.
   2. Click on the Settings tab that is located on the top left just under the repository path
   3. Click on the Secrets section
   4. From the following screen, you can either create organization level secrets (secrets that can be used across all repositories within your organization group) or repository level secrets.

   5. Some secrets examples you may create based on the ispw-sync-build-deploy.yml (Download a template)

      • secrets.TSOUSER
      • secrets.TSOPASS
      • secrets.GITUID
      • secrets.GITHUB_TOKEN
      • secrets.CES_TOKEN

Make a change and build

To make a change to Cobol component TPROG15.cob, perform the following steps: 

1. In Workbench for Eclipse’s Project Explorer view, expand GitPlay>COB.
2. Right-click TPROG15.cob and select Open. The source opens in the editor.
3. On line 8, append the TEST to ...PROGRAM.
   
4. From the File menu, select Save.
5. From the File menu, select Close.

Perform the build action to verify the source generates successfully along with any impacted components

1. In Workbench for Eclipse’s Project Explorer view, Right click on GitPlay project, select Properties, add 

   Code Pipeline

    Nature, then click Apply and Close.
   
   In Workbench for Eclipse’s Project Explorer view, right-click the GitPlay project node and select Properties>

   Code Pipeline

   . The 

   Code Pipeline

    page of the Properties dialog box appears.

2. In the YAML mapping file location field, enter or browse to the YAML mapping file.
3. In the Level field, enter DEV1 as the life cycle level for the project that will be used to load the file into Code Pipeline at that level. The level value is required to perform any Code Pipeline action.

4. Optionally, in the Assignment description field, enter the assignment name to be used for the generate/build process; click Insert Variable, if desired, to choose variables to build the assignment name.

   Warning

   Important

   If no valid value exists for the chosen variable, the Description field in the Containers view will treat the variable as empty, Descriptions longer than 50 characters will be truncated. The default assignment description is ${user} ${branch_name}.

5. Click Apply and Close.

6. In the Project Explorer view’s COB folder, right-click TPROG15.cob and select Code Pipeline>Build. The Console view shows the progress of the build.

   Warning

   Important

   If an Code Pipeline pop-up appears, click YES to continue.

   

7. In the Console view, note the assignment where TPROG15 was loaded. In the example above, TPROG15 was loaded into assignment PLAY004840 at the DEV1 level.
8. Delete the task from container PLAY004840 and close the container.

Submit the change to GitHub

To commit and push the changes to GitHub and trigger the GitHub Workflow, perform the following:

1. To Commit and Push TPROG15, in the Unstaged Changes box, select TPROG15 and click to add it to the Staged Changes box.
   
2. In the Commit Message box, enter a commit message, such as TPROG15 commit.
3. The Push Results dialog box appears.
4. Click Close.

Determine whether the synchronization process completed successfully

Once the TPROG15 is pushed to GitHub, the workflow on GitHub is immediately triggered (for demo purpose, ispw-sync-local-generate-deploy workflow is disabled, workflow ispw-sync-build-deploy is enabled).

1. Visit GitHub repository GitPlay | Actions.
   

2. Once the job completes, click TPROG15 commit to view workflow run detail.
   
   The following is an example of what the sync step will show for a successful Git to Code Pipeline synchronization:

   Finished synchronizing changes from Git to ISPW assignment PLAY005107 at level DEV1
   
    COB/TPROG15.cob                                     -----  Success                               
   
   1 total changes detected during synchronization: Success 1, Failure 0, Skipped 0

   The following is an example of what the build step will show for a successful build:

   Build parameters are being retrieved from the build_automatically input.
   Starting the build process for task 7E5655E16646
   
   ISPW: Set S000248884 - The generate request completed successfully for TPROG15 in PLAY005107. Job ID and name: J0156513 ISPWTPZG
   ISPW: Set S000248884 - The build process completed successfully
   
   The build request completed successfully.

   The following is an example of what the deploy step will show for a successful build:

   Deploy parameters are being retrieved from the deploy_automatically input.
   
   Starting to submit the deploy request for task 7E5655E16646
   ISPW: received set ID: S000248885
   
   ISPW: received URL: http://10.100.12.250:48226/ispw/cw09-47623/sets/S000248885
   
   The deploy request has been submitted.

   Success

   Tip

   Git commit information can be viewed in Workbench within the Code Pipeline Assignment view and the Code Pipeline Release view.

Verify the updates occurred to the Mainframe**

1. In Workbench for Eclipse’s 

   Code Pipeline

   Containers view, find the assignment where TPROG15 was loaded and double-click the assignment. The 

   Code Pipeline

   Tasks view appears.

2. Double-click TPROG15. The source is opened in the editor.

   Warning

   Important

   If a copybook download message appears, click No to not download copybooks.

3. Verify that line 8 shows TEST appended.