Mainframe guide

With gitta Enterprise, AI coding agents work on COBOL, copybooks and JCL at the same time. When one agent changes a field, a paragraph or a program’s interface that another agent’s new code uses, that agent hears about it while it works. You merge with git as usual, and gitta checks the combined work before it reaches the main branch and your mainframe build.

What gitta does for a mainframe team

• It reads COBOL programs, copybooks and JCL. It finds the fields, condition names, paragraphs, program interfaces and job steps that each agent changed or newly uses. See COBOL, copybooks and JCL.
• It warns an agent at its next step when another agent’s change affects its new code.
• It runs inside git merge, git pull and git push to the main branch and checks the combined code there.
• It reports JCL, REXX, CLIST, COBOL and assembler changes that give code more authority, in the merge output, the log and the audit trail. See Security checks on mainframe code.
• It runs your own build or tests on the combined work during the merge, when you give it a gate command.
• It records every warning, check and merge in the audit trail. The trail holds paths, symbols, commits and results, never source code.

Where gitta runs

gitta runs where your agents and pipelines run: developer machines and CI runners with macOS, Linux or Windows. The agents work in a clone or worktree of the repository, and z/OS keeps its own build and run process. With gitta Enterprise, the gitta image runs in zCX inside z/OS, so your DBB pipeline can check each change before the build, see Run gitta on z/OS with zCX.

See Supported platforms for the full list.

Set up from zero

1. Put the source in Git. Keep programs, copybooks and JCL in the repository as UTF-8 text. With Git on z/OS, set the conversion in .gitattributes. See Git and EBCDIC.
2. Install gitta on each machine where agents work and on the CI runners. See Install.
3. Name your copybook directories if copybooks have no file extension. See Copybook directories.
4. List your own libraries and datasets for the security checks, in .gitta-security. See Your own libraries and datasets.
5. Run gitta init once in the repository. Add --gate "COMMAND" if the machine can run a build step or tests. Without a gate, gitta still warns the agents while they work.
6. Commit .gitattributes, .gitta-copybooks and .gitta-security. Every developer, agent and CI runner then uses the same settings.
7. Add the check to CI before the DBB build step. See CI and DBB.

$ cd ~/src/reports
$ gitta init
gitta is set up in reports.

No agent worktrees exist yet. Every worktree an agent tool creates from now on is picked up on its own.
After every step an agent takes, gitta looks at what it changed. When one agent changes a function that another agent's new code calls, gitta tells that agent right away, so it can adapt before anything reaches main.
Merging works as always, with git merge, git pull or git push. No test command is set, so gitta runs no tests during a merge yet. Add one with `gitta init --gate "<your test command>"`.
Claude Code hooks already installed.
When gitta tells an agent about a clash, the agent fixes its code itself and mentions it to you in one sentence in its chat.
gitta never asks you anything. When a merge removes tests or weakens a security check, it says so in the merge output and in the log. The merge goes ahead unless the committed .gitta.toml sets weakened_checks to block.
To share the test command and rules with your team and the CI check, run `gitta init --team` and commit .gitta.toml.

Start your agents the way you always do. `gitta watch` shows what gitta does as it happens, and `tail -f .gitta/gitta.log` follows the same story as plain lines.

Then start the agents as usual. Each agent works in its own worktree, and gitta finds every worktree by itself.

Git and EBCDIC

Moving z/OS source into Git means converting it between EBCDIC and UTF-8. IBM describes the code page side of this in its white paper on Git and EBCDIC characters (IBM Support, code page conversion with Git on z/OS). With AI agents, this matters more. An agent edits UTF-8 text in its worktree, and the change goes back to z/OS through the same conversion. When a code page is wrong, the agent's change and the characters around it can arrive different from what it wrote. gitta checks for this on every agent change, as below.

Git for z/OS keeps the working tree in EBCDIC on z/OS and the repository content in UTF-8. .gitattributes sets the conversion for each kind of file.

# z/OS working tree in EBCDIC (IBM-1047), repository content in UTF-8
*.cbl zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.cpy zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.jcl zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
COPYLIB/* zos-working-tree-encoding=ibm-1047 git-encoding=utf-8

gitta reads the repository content, so it sees the UTF-8 text. A file stored in the repository as EBCDIC bytes cannot be read. gitta then shows it as not analysed and does not treat it as safe.

Set the code page for each folder

EBCDIC code pages of one family store a few characters at different bytes. IBM-1047 keeps [ and ] at X'AD' and X'BD'. IBM-037 keeps them at X'BA' and X'BB', and ¬ and ^ trade places. Many systems hold files in both code pages, often in different libraries. When Git converts a file with the wrong code page, nothing fails. The file still compiles, but [ is now Ý, ] is ¨ and ¬= is ^=.

So give every folder its code page in .gitattributes, and do not rely on one rule for the whole repository. Set it for every kind of mainframe file, also for JCL, REXX, CLIST, assembler and C.

# Programs and copybooks in IBM-1047, REXX execs copied from an IBM-037 library
cobol/** zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
copy/** zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
rexx/** zos-working-tree-encoding=ibm-037 git-encoding=utf-8

gitta reads working-tree-encoding and zos-working-tree-encoding from every .gitattributes file in the repository, with Git’s pattern rules. A later rule wins, and -working-tree-encoding takes the setting away. When you cannot change .gitattributes, put the code pages in a file called .gitta-encoding at the top of the repository. Write one pattern and one code page on each line. Its rules come after the ones in .gitattributes.

# Members copied from SYS1.PROCLIB
proc/* IBM-1047
legacy/rexx/* IBM-037

What gitta checks

The hook tells the agent at once, with code page conversion changed characters, and the finding goes into the audit trail.

• Lines that changed only in characters that EBCDIC code pages store differently, for example [ to Ý or ¬ to ^. This is what a conversion with the wrong code page does. gitta knows IBM-037, IBM-1140, IBM-1047 and IBM-500.
• New replacement characters (U+FFFD). A conversion puts one where it could not map a byte, and the character that stood there is lost.
• A file that mixes UTF-8 text with bytes of another encoding, a UTF-8 file that now holds other bytes, and a file set to an EBCDIC code page in the working tree that now holds UTF-8 text.

An edit that also changes other characters on the line is ordinary work, and gitta treats it as such. When a working tree holds EBCDIC bytes, gitta reads them with the code page set for the file before it compares.

gitta also warns the agent in two cases, as information only:

• A mainframe file has no code page, while .gitattributes sets one for other files.
• A file holds characters such as [, ], ¬ or ^, and its folder has a different code page from a folder next to it. A file copied from one folder to the other changes without an error.

gitta encoding shows how many files have each code page, how many mainframe files have none, and these warnings for the whole repository.

Copybook directories

gitta knows copybooks by their extension: .cpy, .copy and .cbk. Many teams copy PDS members into Git as files without an extension, for example COPYLIB/CTLREC. List the directories that hold copybooks in a file called .gitta-copybooks at the top of the repository, one on each line.

# Directories whose files are copybooks, also without an extension
COPYLIB
app/copy

A copybook is known by its member name, the file name without the extension in upper case. COPY CTLREC finds COPYLIB/CTLREC, copy/ctlrec.cpy or cpy/CTLREC.cbl. A program is known by its PROGRAM-ID.

What an agent sees

In the output below, one agent changes the run date in the copybook CTLREC from PIC 9(6) to PIC 9(8). A second agent adds a MOVE CTL-RUN-DATE to the program RPTHDR. A third agent adds a job step that runs shell commands. gitta status shows all three:

$ gitta status
main is the branch gitta merges finished work into.
  date8 1 file changed, ready to merge
  header 1 file changed, ready to merge
  jobstep 1 file changed, removes tests or weakens a security check; reported when merged, and .gitta.toml decides whether that stops the merge
  date8 changed `CTLREC.CTL-RUN-DATE`, which header's new code in cobol/RPTHDR.cbl uses. Check that the two changes still work together.
  SECURITY: jcl/RPTJOB.jcl by jobstep: newly runs Unix shell commands from batch (`PGM=BPXBATCH`). Shell commands in a batch job run with the job's user and authority. Reported when merged; .gitta.toml decides whether it stops the merge.

While both agents work, the agent in header hears about the copybook change in its own session at its next step. After the copybook change is merged, gitta notes in .gitta/gitta.log that the new code in cobol/RPTHDR.cbl calls CTLREC.CTL-RUN-DATE, which changed on main. The tests at merge time decide. If they fail, the merge output shows the new definition on main.

When you merge jobstep, the merge output, .gitta/gitta.log and the audit trail report the new job step. With weakened_checks set to block, as in CI, the merge stops until the agent changes the step. See Removed tests and weakened checks.

CI and DBB

With IBM Dependency Based Build (DBB) and zAppBuild, run gitta pr-check on a Linux or macOS CI runner before the DBB build step. A pull request that does not merge with another open one, or whose new code uses something another open pull request changed, then stops before it uses mainframe build time.

# on the CI runner, before the DBB build step
gitta pr-check --pr "$FEATURE_REF" --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

The check reads the committed .gitta-copybooks and .gitta-security files, so CI uses the same settings as the agents. See CI/CD integration for teams for required checks, test cost and audit evidence.