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?

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 or host components 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​

Wazi Deploy​

IBM® Wazi Deploy is available as a component of multiple products. It provides a scriptable method to deploy programs to multiple target systems. Wazi Deploy is provided as a Python package, which allows for usage on various operating systems. You can install the Wazi Deploy core package on a z/OS® environment (in a z/OS UNIX System Services file system) or on a distributed environment (x86 or Linux® on Z).

To install and activate the functionalities of Wazi Deploy, see the IBM® Wazi Deploy Program Directory.

After the initial installation with the IBM® Wazi Deploy Program Directory, proceed with the next installation and configuration steps. These steps are described in the Wazi Deploy Host Configuration Guide. Note that there are two options for Wazi Deploy (Python-based deployment or deployment using Ansible), which will each entail a different installation process:

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