Contents

Run gitta on z/OS with zCX

IBM z/OS Container Extensions (zCX) runs Linux containers for IBM Z inside z/OS. gitta Enterprise runs there as a container, so your DBB pipeline can check each change on z/OS itself, before the build step uses the change.

How it fits together

A zCX instance is a Linux appliance that z/OS runs as a started task. It gives you the Docker command line, and it runs images built for the s390x architecture (IBM, z/OS zCX Guide). Your DBB pipeline clones the repository into a z/OS UNIX directory and then runs the zAppBuild build script with groovyz (IBM, Integrating IBM z/OS platform in CI/CD pipelines with GitLab).

gitta joins between these two steps:

The z/OS NFS server exports the directory that holds the DBB workspace.
A Docker volume in zCX mounts that export.
The pipeline starts the gitta container on the volume. gitta compares the change with the other open changes and writes the result.
The pipeline reads the result and starts the DBB build only when the check finds no clash.

Prerequisites

A zCX instance, and a zCX user who can run docker through the zCX SSH command line on port 8022.
The z/OS NFS server with AT-TLS, as the zCX Guide describes for NFS volumes. This needs APAR OA62357, NFS version 4 and the safexp security setting.
The HAProxy container in the zCX instance that sends NFS traffic to the z/OS NFS server with TLS. The zCX Guide gives its haproxy.cfg.
A z/OS user ID for the zCX client certificate, with read access to the DBB workspace directory.
A container registry that the zCX instance can reach. zCX loads images from a registry, either an external one or a private registry that you run yourself.
gitta Enterprise. The zCX image has the COBOL, copybook and JCL support of the Mainframe guide.

Load the image into zCX

The gitta zCX image holds the gitta command and Git, on Debian for linux/s390x. Build it on any machine with Docker Buildx, from the folder that holds the gitta and gitta Enterprise sources, and push it to your registry:

Terminal

$ docker buildx build --platform linux/s390x -f gitta-enterprise/deploy/zcx/Dockerfile \
    -t registry.example.com/gitta-zcx:0.1.0 --push .

Then pull it in the zCX instance and check it:

Terminal

$ ssh -p 8022 [email protected]
$ docker pull registry.example.com/gitta-zcx:0.1.0
$ docker run --rm registry.example.com/gitta-zcx:0.1.0 --version
gitta 0.1.0

If you use a private registry without TLS, add it as the insecure registry of the zCX instance. IBM recommends this only for isolated tests. See the chapter on Docker registries in the zCX Guide.

Mount the repository

Create a Docker volume for the exported z/OS UNIX directory. The address is the DVIPA of the zCX instance, not the address of the NFS server, because HAProxy sends the traffic on to the NFS server:

Terminal

$ docker volume create --driver local --opt type=nfs4 \
    --opt o=addr=10.0.1.2,ro --opt device=:/hfs/u/dbb/workspace,mvsmnt dbb-workspace

Use the address of your zCX instance and the path of your DBB workspace. The path starts with /hfs for a z/OS UNIX directory, as in the zCX Guide. Inside the container, every file on the volume belongs to nobody:nogroup, and z/OS checks access with the user ID of the client certificate. The gitta image tells Git to trust the mounted repository, so Git reads it as it is.

Mount the volume read-only. gitta reads the repository on the volume, makes its own clone in the container and checks the change in that clone. The workspace that DBB builds stays as the pipeline left it.

Add the check to the DBB pipeline

Add a step after the clone step and before the build step. The step runs the gitta container in zCX through the zCX SSH command line:

# after the clone step, before the DBB build step
ssh -p 8022 [email protected] docker run --rm -v dbb-workspace:/src:ro \
  --entrypoint sh registry.example.com/gitta-zcx:0.1.0 -c "'
    git clone -q /src/app /repo/app && cd /repo/app &&
    git fetch -q origin +refs/pr/*:refs/pr/* &&
    gitta pr-check --pr HEAD --name $CHANGE --base origin/main \
      --other refs/pr/119=#119 --other refs/pr/121=#121 --json'" > gitta.json
jq -e 'all(.[]; .merges and (.warnings | length == 0))' gitta.json

# only then start the mainframe build
groovyz dbb-zappbuild/build.groovy --workspace "$WORKSPACE" --application app --impactBuild

In the workspace, the pipeline checks out the change under test and fetches the other open changes under refs/pr/. $CHANGE is the name of the change under test, for example #124. gitta pr-check exits with 0 when it finds clashes, and the jq line decides when the step fails. It exits with 3 when the change removes tests or weakens checks and weakened_checks is block. The check reads the committed .gitta-copybooks and .gitta-security files, so it uses the same settings as your agents. For the rule on which change goes first, see Which pull request goes first.

What the user sees

When the check finds no clash, the step passes and DBB builds as before. When one change widens a copybook field and another change adds code that uses the field, gitta.json names the field, the program and the other change, and the pipeline stops before the build:

Terminal

$ jq -r '.[].warnings[]' gitta.json
#119 changed `CUSTREC.CUSTOMER-NAME`, which #124's new code in src/CUSTUPD.cbl uses. Check that the two changes still work together.

The developer or agent brings the change up to date with the other one, adapts the program and pushes again. The next pipeline run checks it again. For the full list of what gitta follows in COBOL, copybooks and JCL, see COBOL, copybooks and JCL.