Skip to main content

Installing and configuring your tools

This page contains installation and setup instructions for the components of our recommended CI/CD pipeline (described in our Introduction to CI/CD for z/OS®), as well as links to installation documentation for specific products. The CI/CD pipeline is based on Git for source code management (SCM), while IBM® Dependency Based Build (DBB) and zAppbuild are required for the Build component. For the remaining components of the CI/CD pipeline, enterprises will generally select one technology for each component category, although sometimes more than one IDE option is selected (depending on developer preference).

Note: We have listed common options for each CI/CD component below. However, if you do not see the option your enterprise has selected for a particular component, that does not necessarily mean it cannot align with our guidance. For most tools being used elsewhere, you can integrate them into the pipeline as long as they are compatible with z/OS application development and bring value to your enterprise.

Not sure what tool to pick for certain CI/CD component? See our documentation on How do you select what tool to use for each component.

Integrated development environment​

Who needs to install the integrated development environment (IDE), and where?

  • The integrated development environment (IDE) will need to be installed by z/OS application developers on their local workstations or be included in the enterprise software distribution process. IBM supports the following IDE options for z/OS application development:
  • Some IDE options have host components that require a system programmer to configure.

IBM Developer for z/OS​

IBM's Eclipse-based IDE IBM Developer for z/OS (IDz) needs to be installed on the local workstations of the z/OS application developers.

IDz also contains various z/OS host components that need to be installed by the system programmer. Please refer to the host install and configuration section in the IDz documentation or use the interactive host configuration assistant. IDz can be enhanced with problem determination capabilities and much more via several extensions of the IBM Application Delivery Foundation for z/OS (ADFz) suite.

VS Code​

IBM Developer for z/OS on VS Code requires the Visual Studio Code (VS Code) IDE to be installed on the local workstations of z/OS application developers, along with the IBM Z® Open Editor and IBM Z Open Debug VS Code extensions. These extensions are shipped with advanced features as supported product components of IBM Developer for z/OS Enterprise Edition (IDzEE). IBM Z® Open Editor is also available with the base functionality as a free-of-charge VS Code extension.

The VS Code extensions communicate with the mainframe backend via the Zowe framework. The mainframe connection can be established either via z/OSMF and SSH, or alternatively via IBM RSE API. Additional details can be found in the IDz on VS Code documentation for setting up the integrations to interact with z/OS.

Source code management​

We recommend using Git-based source code management. Clients can pick from several Git providers, including those listed in the following section for Initializing a repository in the Git provider for mainframe application.

Who needs to install the source code management (SCM), and where?

  • Regardless of the Git provider selected, Git will need to be installed on both developer machines, and on z/OS.
    • Developer machines: Developers can obtain Git the same way they would for non-mainframe development. IDEs typically come with their own Git client; other popular options are referenced in the documentation of Git. For instance, Git for Windows brings Git including a BASH emulation to Windows.
    • z/OS: Git runs under z/OS UNIX® System Services. It is installed by a system programmer via the Open Enterprise Foundation for z/OS SMP/E package.

Once Git is set up on the developer machines and z/OS build environments, it works together with the enterprise Git provider for the organization. The enterprise's team that handles the Git provider will usually assist to provide the basic organization or repository setup for the z/OS application team(s), and will also provide guidance on the recommended protocol for communicating with the central Git provider. The z/OS application teams will then maintain these repositories.

Installing and configuring Git on z/OS​

IBM provides an SMP/E install of Git as part of the Open Enterprise Foundation for z/OS FMID HAMN110. The latest maintenance and updates are distributed via PTFs, which are documented in the Fix List for IBM Open Enterprise Foundation for z/OS.

Initializing a repository in the Git provider for mainframe applications​

The following tabs describe how to initialize a repository in common Git provider options.

Initialize a repository in Azure Repos​

  1. In Azure DevOps' web interface, follow the Azure documentation to Create a new project in Azure.
  2. Initialize a new repo in Azure:
    1. From your new Project page select Repos and the "Initialize" option. Your repo is created with the name of your project with a "main" branch.
    2. From your new Repo's page select "Clone", "SSH", and "Manage SSH Keys". This takes you to the "New Key" page where you can add your z/OS SSH public key.
    3. Once the SSH key is added, go back to the repo's clone button to cut & paste the SSH-based URL for cloning on UNIX System Services. For example, a project named "Azure-Mortgage-SA"' would look like git@ssh.dev.azure.com:v3/Azure-Repo-DBB/AzDBB/.
    4. On UNIX System Services run git clone followed by the URL. Your new local repo is ready for the next step – PDS migration.

Note: Instead of cloning with SSH you can clone with HTTPS. For example, you can clone using a personal access token (PAT) that is generated from the Azure UI. Apply the PAT to the clone command, for example: -https://<USER>:<PAT>@<my.azure.com/repo uri>. Other alternatives are Azure's OAuth token, adding extraHeaders in the clone command to enable the basicSecurity option, Azure's System.AccessToken pipeline variable, or Git's built-in Credential Manager.

To migrate a mainframe application to your newly-initialized repository, configure the DBB Migration Tool, and finalize the changes and push to Git. Information on these steps can be found on the DBB Migration Tool page.

Build​

IBM Dependency Based Build (DBB) is the recommended build tool for z/OS applications. This is complemented by the zAppBuild framework, which helps facilitate your build process using DBB APIs. Many clients start by using zAppBuild and enhancing it to their needs, for example by adding new language scripts, or by modifying the existing build processing logic.

tip

If you prefer a configuration-based build framework over a script-based build framework, the DBB zBuilder is an alternative to zAppBuild, and is available in DBB version 3.0.0 and above. Information about setting up and configuring the DBB zBuilder can be found in the DBB documentation page Setting up and configuring zBuilder.

This section provides a set of instructions for how you can make zAppBuild available in your Git provider and how to synchronize new features of zAppBuild into your customized fork.

Note: zAppBuild releases new versions through the main branch. New contributions are added first to the develop branch, which then will be reviewed and merged to the main branch.

The IBM DBB samples repository contains additional utilities that enhance or integrate with the other DBB build processes.

Who needs to install DBB, and where?

  • System programmers install DBB toolkit on z/OS.
    • Set up Db2® for z/OS or Db2 for LUW (Linux®, UNIX, and Windows) for the DBB metadata store.
    • See IBM Documentation on Installing and configuring DBB.
  • Developers using IDz as their IDE must add the DBB integration to their installation of IDz in order to use DBB's user build feature.

Who needs to set up zAppBuild (and the IBM DBB samples repository), and where?

  • The build engineer and/or DevOps team (in DAT roles: Build specialist and/or Pipeline specialist) should set this up with the enterprise's Git provider.
    • Steps for making a copy of the zAppBuild repository available in your enterprise's preferred Git provider are provided in the following section.
    • If the IBM DBB samples repository is needed, it can be copied from its IBM GitHub page to your Git provider in a similar manner to the zAppBuild repository.

Making zAppBuild available in your Git provider​

Before you start your customization of zAppBuild, you must first create a clone of IBM's zAppBuild repository and store the clone in your Git provider of choice. This could be any Git provider, such as GitHub, GitLab, Bitbucket or Azure Repos, and so on. If you have done this already, feel free to move to the next section.

Here are the steps to make the zAppBuild repository available in a central repository on your Git provider:

  1. On your local workstation, use your browser and log on to your Git provider. Follow the instructions in your Git provider to create a new repository, which will be the new “home” of your customized version of zAppBuild.
    1. We suggest "dbb-zappbuild" as the new repository/project name, but you can use another name if you prefer.
    2. Set the repository's visibility according to your needs.
    3. Do not initialize the repository yet.
      • Your Git provider will create the repository, but it is not yet initialized. On most Git providers, the repository creation process will end on a page with information on how to share an existing Git repository. Leave the browser open.
  2. Clone IBM's public zAppBuild repository to your local workstation. You can use your local workstation's terminal to complete this step (for example, Git Bash in Windows, or Terminal on MacOS).
    • If you are using IBM Developer for z/OS (IDz) as your IDE, you can use its Local Shell. Wazi for VS Code and Wazi for Dev Spaces also both have Terminal windows. (We documented the steps in this guide using a terminal.)

    1. In the terminal, navigate to the folder where you would like to clone the repository.

    2. Retrieve the Git repository URL or SSH path from IBM's public zAppBuild repository:

      Retrieving the Git repository URL from IBM&#39;s public zAppBuild repository

    3. In your terminal, enter the command for cloning the repository. (The following command uses the Git repository URL, but the SSH path can also be used if you have SSH keys set up.):

      git clone https://github.com/IBM/dbb-zappbuild.git

      • Example Git clone command with output in a terminal:

        Example Git clone command with output in a terminal

  3. Follow the instructions of your Git provider to push the contents of your newly-cloned local repository (from Step 2) to the central repository on your Git provider (created in Step 1). (Note: Exact instructions may vary from Git provider to Git provider.)

    1. Within the terminal session, execute the following commands to push an existing Git repository:

      • Replace <existing_repo> with the path to your newly-cloned local repository.
      • Replace <Your central Git repository> with the URL to the new central repository on your Git provider. (For example, with GitLab as the Git provider, the URL might look similar to git@gitlab.dat.ibm.com:DAT/dbb-zappbuild.git.)
      cd <existing_repo>
      git remote rename origin old-origin
      git remote add origin <Your central Git repository>
      git push -u origin –all
      git push -u origin --tags

    2. On the Git provider's webpage for your new central repository in the browser, you will find that the repository is now populated with all of zAppBuild's files and history, just like on IBM's public zAppBuild repository.

      • The following screenshot shows an example of a populated central zAppBuild repository with GitLab as the Git provider:

        Example of a populated central zAppBuild repository in GitLab&#39;s web UI

Updating your customized version of zAppBuild​

Once you have a clone of zAppBuild in your Git provider, you can customize the properties and scripts within it according to your organization's needs. The zAppBuild wiki documents some possible zAppBuild customization scenarios. Additionally, IBM regularly releases new versions of the official zAppBuild repository to deliver enhancements and bug fixes. To integrate the latest official zAppBuild updates into your customized version of zAppBuild, you can use the following process:

  1. Locate the internal Git repository and create a new Git branch. This is a good practice to validate the changes first. In this example, the new branch is called update-zappbuild.
  2. Add a new Git remote definition to connect to IBM's official public zAppBuild GitHub repository. (Note: This step requires internet connectivity.)

    1. First, list the remotes by issuing git remote -v:

      Output from initial listing of the remote tracked repositories

      • For more on Git remotes, see the git-remote documentation.

    2. Add a new remote named zappbuild-official to connect to GitHub by issuing the following command:

      git remote add zappbuild-official https://github.com/IBM/dbb-zappbuild.git

    3. Verify that the new remote is available by issuing the command to list the remotes again: git remote -v:

      Output from listing the remote tracked repositories after adding the zappbuild-official remote

    4. Fetch the latest information from the official repository, by executing a Git fetch for the official dbb-zappubuild repository:

      git fetch zappbuild-official

      Output from Git fetch of the zappbuild-official remote

    5. Make sure that your feature branch is checked out, before attempting to merge the changes from zappbuild-official. To merge the changes run into your branch update-zappbuild, run the following command:

      git merge zappbuild-official/main

      Merge conflict when attempting to merge in changes from zappbuild-official

      Potentially, you face merge conflicts. In the above case, the merge processor could not automatically resolve the utilities/ImpactUtilities.groovy.

      Run the command git status to see which files changed:

      Output of Git status to view files changed during the merge attempt

    6. Open the unmerged files and resolve them manually. Either use the terminal, or an IDE for this task.

      tip

      The Git integration in many modern IDEs (for example, VS Code) is able to provide a side-by-side comparison highlighting the diff between your feature branch and the incoming changes from the merge attempt (in this case, from zappbuild-official). This can help make manual resolution of any merge conflicts much easier.

    7. Commit the changes and verify them with a sample application before committing it (or opening a pull request to commit it) to your main branch that is used for all your production DBB builds.

Artifact repository​

The artifact repository is often already in-place as part of the enterprise's non-mainframe CI/CD pipeline.

Who needs to set up the artifact repository, and where?

  • Generally, the DevOps team (pipeline specialist) will work to set this up for z/OS application teams, as well.

Artifact repository options​

  • Azure Artifacts
  • JFrog Artifactory
  • Sonatype Nexus
  • UrbanCode® Deploy (UCD) CodeStation

Deployment manager​

Who needs to install the deployment manager, and where?

  • Depending on the software selected, the deployment manager might require an agent on the z/OS side, which can be set up by a system programmer (infrastructure team). (Alternatively, the pipeline orchestrator could SSH into z/OS.)

Deployment manager options​

  • UrbanCode Deploy (UCD)
  • Wazi Deploy

Pipeline orchestrator​

The pipeline orchestrator is often already in-place as part of the enterprise's non-mainframe CI/CD pipeline.

Who needs to set up the pipeline orchestrator, and where?

  • Generally, the DevOps team (pipeline specialist) will work to set this up for z/OS application teams, as well.
  • The pipeline orchestrator often requires an agent or runner on the z/OS side, which can be set up by a system programmer (infrastructure team). (Alternatively, the pipeline orchestrator could SSH into z/OS.)

Pipeline orchestrator options​

  • Azure Pipeline
  • GitHub Actions
  • GitLab CI
  • Jenkins

Resources​

This page contains reformatted excerpts from the following documents:

Last updated on

On this page