Setting Up a GitHub Actions CI/CD Pipeline for RPG, Step by Step

Scope note, read first. RPG Unit Testing with RPGUnit in 2026 already covers a CI integration for RPGUnit built around a Jenkins pipeline and a generic PASE shell script. This article does not repeat that walkthrough. It covers a different, concrete CI platform — GitHub Actions with a self-hosted runner — end to end: registering the runner, the exact workflow YAML for checkout/build/test, how a TOBi (the open-source IBM i build tool formerly named Bob) build step fits into a job, and a separate, explicitly gated promotion job. If your shop uses Jenkins, read the RPGUnit article instead; if it uses GitHub Actions, this is the one with the matching YAML.

Who this is for: an RPG team that already has source in Git (see Source control for IBM i: managing your RPG and CL source with Git and RDi) and wants a working GitHub Actions pipeline that compiles ILE RPG objects on a real IBM i partition and gates merges on RPGUnit test results, not just on the compile succeeding.

Verification level: the GitHub Actions runs-on/self-hosted-runner syntax below is checked against GitHub’s own current documentation (IBM DOC CHECKED equivalent — GitHub’s official docs). The build-tool naming (Bob → TOBi) and its general GNU-Make-based incremental build model are checked against the tool’s own GitHub repository. The RPGUnit RURUN/TAP details reuse the facts already established in RPG Unit Testing with RPGUnit. Everything specific to how makei/TOBi is invoked on the command line is NOT TESTED and STATIC CHECKED at best — this article has no compiler or runtime access to a live IBM i partition, and the tool’s installation/usage documentation site could not be fully retrieved during research (noted explicitly below). Treat every YAML and shell snippet as a starting point to adapt and test on your own system, not as a drop-in, verified pipeline.

Why a self-hosted runner, not GitHub’s hosted runners

GitHub’s hosted runners are ephemeral Linux, Windows, or macOS virtual machines — none of them is IBM i, and none can run CRTRPGMOD/CRTSRVPGM or RURUN directly. Two architectures bridge that gap:

  1. A self-hosted runner that is itself IBM i PASE, so build and test steps execute directly on the partition.
  2. A self-hosted runner on any OS that can reach the partition over SSH, running the actual IBM i commands remotely (the approach this article uses, because it works whether the runner is a small Linux VM, a container, or a machine sitting next to the partition, and keeps the GitHub Actions runner process itself off the production partition).

Confirmed per GitHub’s own documentation: a self-hosted runner automatically receives a self-hosted label, one OS label (linux, windows, or macOS), and one architecture label (x64, ARM, or ARM64) when registered, and a workflow targets it by listing labels under runs-on. GitHub’s documented example: runs-on: [self-hosted, linux, ARM64] — a runner must match every label listed.

Step 1 — Register the self-hosted runner

From the repository’s Settings → Actions → Runners → New self-hosted runner, GitHub generates a one-time registration token and a short setup script for the runner’s OS. Run it on the machine that will reach your IBM i over SSH (a small Linux VM is sufficient):

# Example shape of GitHub's generated commands (token and URL are per-repository and one-time)
mkdir actions-runner && cd actions-runner
curl -o actions-runner-linux-x64.tar.gz -L https://github.com/actions/runner/releases/download/vX.Y.Z/actions-runner-linux-x64-X.Y.Z.tar.gz
tar xzf ./actions-runner-linux-x64.tar.gz
./config.sh --url https://github.com/<org>/<repo> --token <token-from-github>
./run.sh

Give the runner a custom label during ./config.sh (it prompts for additional labels) so your workflow can target it specifically, for example ibmi-pipeline. Install it as a service (./svc.sh install && ./svc.sh start) so it survives a reboot — see GitHub’s own self-hosted runner documentation for the service-install steps, which are OS-specific and not reproduced here.

Store IBM i connection details as repository secrets, not in the workflow file: IBMI_HOST, IBMI_USER, IBMI_SSH_KEY (a private key for a dedicated key pair scoped to the build user — preferred over a password secret), and IBMI_HOST_KEY (the IBM i SSH server’s public host key, used to verify the server’s identity on every connection). Settings → Secrets and variables → Actions → New repository secret, for each.

Get IBMI_HOST_KEY once, out-of-band, rather than trusting whatever key the pipeline happens to see on its first connection (blind trust-on-first-use defeats the point of host-key verification): run ssh-keyscan -t ed25519 <your-ibmi-host> from a trusted machine, and separately confirm the fingerprint it returns matches the key actually configured on the IBM i partition’s SSH server before storing the output line as the IBMI_HOST_KEY secret value.

Step 2 — The repository layout

.
├── .github/
│   └── workflows/
│       └── rpg-ci.yml
├── QRPGLESRC/
│   ├── ORDVAL.RPGLE
│   └── ORDVALTEST.RPGLE
├── QCLSRC/
├── iproj.json
└── Rules.mk

iproj.json and Rules.mk are the build-tool’s own project files, shown below.

Step 3 — The build tool: TOBi (formerly Bob)

The RPG community’s long-standing open-source build system for IBM i was known as Bob (Better Object Builder) until it was renamed TOBi (The Object Builder for i) in 2025, per the project’s own GitHub repository. The rename is worth knowing before you search for documentation — older articles, blog posts, and even some existing AS400Decoded content refer to it as “Bob”; the underlying project is the same.

Confirmed from the project’s GitHub repository: TOBi’s build engine is GNU Make — object dependencies are declared with standard makefile syntax, and the tool “only compiles objects that need recompiling,” rebuilding dependents when something they depend on changes. The project ships as open source under the Apache 2.0 license.

A minimal iproj.json for the sample layout above (illustrative — NOT TESTED, adapt to your project’s actual target library and object names):

{
  "version": "0.0.1",
  "description": "RPG CI/CD sample project",
  "objlib": "MYBUILDLIB",
  "curlib": "MYBUILDLIB",
  "includePath": ["QRPGLESRC"]
}

A minimal Rules.mk describing one service program and its RPGUnit test:

# Rules.mk — illustrative, NOT TESTED against a live build
ORDVAL.SRVPGM: ORDVAL.MODULE
ORDVALTEST.SRVPGM: ORDVALTEST.MODULE ORDVAL.SRVPGM

This article’s limit on TOBi/Bob syntax. TOBi’s installation and usage documentation is published at a documentation site that render its command reference client-side; that site and the project’s own README could not be retrieved as readable text during research for this article, so the exact current makei subcommand flags are NOT TESTED and not independently confirmed beyond the general build-engine description above (GNU Make, incremental compilation) and the iproj.json/Rules.mk file-based project model, which the repository’s file listing and the general IBM i developer documentation for build configuration both corroborate. Confirm the exact invocation syntax against the project’s own current documentation or makei --help on your runner before relying on the command shown in Step 4.

Step 4 — The GitHub Actions workflow

# .github/workflows/rpg-ci.yml
name: RPG CI

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  build-and-test:
    runs-on: [self-hosted, ibmi-pipeline]
    steps:
      - name: Checkout
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Start ssh-agent and load the IBM i deploy key
        env:
          IBMI_SSH_KEY: ${{ secrets.IBMI_SSH_KEY }}
        run: |
          # Loads IBMI_SSH_KEY into a per-job ssh-agent so later steps can
          # authenticate without writing the private key to a shared file
          # or passing it on a command line. SSH_AUTH_SOCK/SSH_AGENT_PID are
          # exported via GITHUB_ENV because each `run:` step is a separate
          # shell process.
          eval "$(ssh-agent -s)"
          echo "SSH_AUTH_SOCK=${SSH_AUTH_SOCK}" >> "$GITHUB_ENV"
          echo "SSH_AGENT_PID=${SSH_AGENT_PID}" >> "$GITHUB_ENV"
          ssh-add - <<< "${IBMI_SSH_KEY}"

      - name: Pin the IBM i host key
        env:
          IBMI_HOST_KEY: ${{ secrets.IBMI_HOST_KEY }}
        run: |
          # Writes the known-good host key captured out-of-band in Step 1,
          # so every ssh/rsync call below verifies the server's identity
          # against a pinned key rather than trusting-on-first-use or
          # disabling host-key checking.
          mkdir -p ~/.ssh
          chmod 700 ~/.ssh
          printf '%s\n' "${IBMI_HOST_KEY}" > ~/.ssh/known_hosts
          chmod 600 ~/.ssh/known_hosts

      - name: Copy source to IBM i build library source
        env:
          IBMI_HOST: ${{ secrets.IBMI_HOST }}
          IBMI_USER: ${{ secrets.IBMI_USER }}
        run: |
          # Illustrative: sync the working copy to the IFS staging directory
          # the build user owns on the IBM i partition. Adjust paths to your
          # own layout; NOT TESTED against a live partition.
          rsync -az --delete \
            -e "ssh -o StrictHostKeyChecking=yes -o UserKnownHostsFile=${HOME}/.ssh/known_hosts" \
            ./ "${IBMI_USER}@${IBMI_HOST}:/home/${IBMI_USER}/ci/${{ github.run_id }}/"

      - name: Build with TOBi (makei)
        env:
          IBMI_HOST: ${{ secrets.IBMI_HOST }}
          IBMI_USER: ${{ secrets.IBMI_USER }}
        run: |
          # Illustrative invocation; confirm exact makei syntax against your
          # TOBi/Bob installation before relying on this. NOT TESTED.
          ssh -o StrictHostKeyChecking=yes -o UserKnownHostsFile="${HOME}/.ssh/known_hosts" \
            "${IBMI_USER}@${IBMI_HOST}" \
            "cd /home/${IBMI_USER}/ci/${{ github.run_id }} && makei build"

      - name: Run RPGUnit tests (TAP output)
        env:
          IBMI_HOST: ${{ secrets.IBMI_HOST }}
          IBMI_USER: ${{ secrets.IBMI_USER }}
        run: |
          # RURUN / RUCALLTST and TAP output are documented in the RPGUnit
          # article this one cross-links; see that article for the TAP
          # format details and the RPGUnit install steps themselves.
          ssh -o StrictHostKeyChecking=yes -o UserKnownHostsFile="${HOME}/.ssh/known_hosts" \
            "${IBMI_USER}@${IBMI_HOST}" \
            "system \"RURUN TSTPGM(MYBUILDLIB/*ALL) OUTPUT(*TAP)\"" \
            > rpgunit-results.tap

      - name: Validate TAP results and fail on any non-pass condition
        run: |
          set -euo pipefail
          TAP_FILE=rpgunit-results.tap

          # An empty or missing file means the previous step produced
          # nothing usable (a dropped SSH connection, a crashed RURUN call,
          # or similar) — that is a failure, not a pass, even though no
          # "not ok" line exists to grep for.
          if [ ! -s "$TAP_FILE" ]; then
            echo "::error::TAP results file is missing or empty ($TAP_FILE); treating as a failed run."
            exit 1
          fi

          # A valid TAP stream declares its test count up front as "1..N".
          # Require that plan line and extract N, rather than assuming any
          # "ok"/"not ok" text in the file is trustworthy on its own.
          PLAN_LINE=$(grep -m1 -E '^[0-9]+\.\.[0-9]+$' "$TAP_FILE" || true)
          if [ -z "$PLAN_LINE" ]; then
            echo "::error::No TAP plan line (N..M) found in $TAP_FILE; malformed TAP output cannot be trusted as a pass."
            exit 1
          fi
          PLANNED=$(echo "$PLAN_LINE" | sed -E 's/^[0-9]+\.\.([0-9]+)$/\1/')

          # Zero planned tests is explicitly a failure: a test run that
          # executes nothing must not report success just because it also
          # produced no "not ok" line.
          if [ "$PLANNED" -eq 0 ]; then
            echo "::error::TAP plan reports 0 tests executed; an empty test run is not a pass."
            exit 1
          fi

          # The number of actual result lines must match the plan. Fewer
          # lines than planned means the run was cut short (for example by
          # a crash partway through); more or duplicated lines mean the
          # output is not well-formed TAP. Either case is untrustworthy.
          RESULT_COUNT=$(grep -cE '^(not )?ok ' "$TAP_FILE" || true)
          if [ "$RESULT_COUNT" -ne "$PLANNED" ]; then
            echo "::error::TAP plan declared ${PLANNED} test(s) but ${RESULT_COUNT} result line(s) were found; treating incomplete or malformed output as a failure."
            exit 1
          fi

          if grep -q '^not ok' "$TAP_FILE"; then
            echo "::error::One or more RPGUnit tests failed:"
            grep '^not ok' "$TAP_FILE"
            exit 1
          fi

          echo "All ${PLANNED} RPGUnit test(s) passed."

      - name: Archive TAP results
        if: always()
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: rpgunit-results
          path: rpgunit-results.tap

Notes on this workflow, consistent with GitHub’s documented syntax:

  • runs-on: [self-hosted, ibmi-pipeline] targets the self-hosted runner registered in Step 1, using the custom label given at registration time, combined with the default self-hosted label — GitHub’s documentation confirms a runner must match every label listed for the job to be scheduled on it.
  • actions/checkout and actions/upload-artifact are pinned to a full-length commit SHA, not a mutable tag such as @v4 — see “Pinning actions: why @v4 is not enough” below for why the tag alone is not treated as sufficient here.
  • Every ssh/rsync call explicitly sets StrictHostKeyChecking=yes and points UserKnownHostsFile at the known_hosts file written from the pinned IBMI_HOST_KEY secret, rather than relying on whatever (if anything) is already configured for the runner’s default SSH client. None of the steps disables host-key checking or falls back to accepting an unknown key.
  • The build and test steps run on the runner, not inside the IBM i partition itself — every IBM i-side command is sent over ssh. If your runner is IBM i PASE, drop the ssh/rsync wrapping and run makei build and the system "RURUN ..." call directly as shell steps (you would still need the host-key-pinning step if that PASE environment reaches the partition’s SSH server over the network rather than running on it directly).
  • The TAP-validation step requires a well-formed plan line, a matching count of result lines, and at least one planned test, before it even looks for not ok — an empty, truncated, or malformed TAP file fails the job instead of silently reporting success.

Pinning actions: why @v4 is not enough

actions/checkout@v4 and similar major-version tags are not immutable pins. Per GitHub’s own security hardening guidance for GitHub Actions, a tag — including a major-version tag like v4 — can be moved or deleted if an attacker gains access to the repository that publishes the action; GitHub’s documented recommendation is to pin third-party (and, for defense in depth, first-party) actions to a full-length commit SHA, with the version shown only as a trailing comment for readability (as in actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 above). A dependency lockfile, where supported, supersedes SHA pinning by recording exact commits and verifying source repositories at run time; where that isn’t available, SHA pinning is the documented alternative — a bare @v4 reference is neither.

Step 5 — A separate, gated promotion job

CI that only compiles and tests is not yet a deployment pipeline. Add a second job that runs only after build-and-test succeeds, and only on main (never on a pull request from a fork, and never without an explicit approval gate):

  promote-to-test-library:
    needs: build-and-test
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: [self-hosted, ibmi-pipeline]
    environment:
      name: ibmi-test-library   # GitHub Environments can require manual approval here
    steps:
      - name: Start ssh-agent and load the IBM i deploy key
        env:
          IBMI_SSH_KEY: ${{ secrets.IBMI_SSH_KEY }}
        run: |
          # Each job runs on a fresh shell/filesystem, even on the same
          # self-hosted runner, so this job repeats the same ssh-agent and
          # host-key setup as build-and-test rather than assuming anything
          # from that job's steps is still in place.
          eval "$(ssh-agent -s)"
          echo "SSH_AUTH_SOCK=${SSH_AUTH_SOCK}" >> "$GITHUB_ENV"
          echo "SSH_AGENT_PID=${SSH_AGENT_PID}" >> "$GITHUB_ENV"
          ssh-add - <<< "${IBMI_SSH_KEY}"

      - name: Pin the IBM i host key
        env:
          IBMI_HOST_KEY: ${{ secrets.IBMI_HOST_KEY }}
        run: |
          mkdir -p ~/.ssh
          chmod 700 ~/.ssh
          printf '%s\n' "${IBMI_HOST_KEY}" > ~/.ssh/known_hosts
          chmod 600 ~/.ssh/known_hosts

      - name: Promote compiled objects to the shared test library
        env:
          IBMI_HOST: ${{ secrets.IBMI_HOST }}
          IBMI_USER: ${{ secrets.IBMI_USER }}
        run: |
          # Illustrative: move objects from the per-run build library into
          # a shared test library once CI has passed. NOT TESTED.
          ssh -o StrictHostKeyChecking=yes -o UserKnownHostsFile="${HOME}/.ssh/known_hosts" \
            "${IBMI_USER}@${IBMI_HOST}" \
            "CALL PGM(MYLIB/PROMOTE) PARM('MYBUILDLIB' 'TESTLIB')"

The environment: key is GitHub’s documented mechanism for attaching required reviewers to a job — configuring an environment named ibmi-test-library with required reviewers in the repository’s Settings means this job pauses for a human approval before it runs, even though the workflow file itself does not change. This matters specifically for IBM i: unlike a web app’s blue/green deployment, promoting RPG objects into a shared test or production library is rarely instantly reversible, so an explicit human gate between “tests passed” and “objects moved” is a deliberate safety control, not friction to engineer away.

This article stops at the test library. Promoting from a test library to production is a separate, higher-stakes step that should have its own explicit approval gate (a second environment: with its own reviewers) and is intentionally left out of the workflow above — wire it the same way, with its own named environment and reviewers, once the test-library promotion has been running reliably.

How this differs from the Jenkins example in the RPGUnit article

RPGUnit article (Jenkins)This article (GitHub Actions)
CI platformJenkins, agent labeled ibmi-paseGitHub Actions, self-hosted runner reached over SSH
Where commands runDirectly in the Jenkins agent’s PASE shellOn the runner host, via ssh to the IBM i partition
Test gateJenkins TAP plugin / archived artifactgrep on the TAP file, failing the job directly; TAP archived as a workflow artifact
Promotion stepNot coveredA separate needs:-gated job using a GitHub Environment with required reviewers
Build tool namingReferred to as “Bob”Referred to by its current name, TOBi (formerly Bob)

If your team is deciding between the two, the deciding factor is almost always “which CI platform do we already run” — the underlying IBM i commands (makei build, RURUN ... OUTPUT(*TAP)) are the same regardless of which orchestrator calls them.

Common mistakes

  • Putting IBM i credentials directly in the workflow YAML instead of repository secrets. Secrets are masked in logs and are the documented, intended mechanism for this.
  • Skipping the promotion gate and letting the build-and-test job itself move objects into a shared library on every green build. Keep promotion as a separate job with its own needs: and its own approval gate.
  • Assuming a hosted GitHub runner can reach an on-premises IBM i. It generally cannot, unless the partition is reachable from GitHub’s cloud runners over the public internet with appropriate firewall rules — a self-hosted runner inside your network is the documented pattern for this exact situation.
  • Treating a major-version tag like uses: actions/checkout@v4 as a pin. It isn’t — tags can be moved or deleted, and GitHub’s own hardening guidance is to pin to a full-length commit SHA (as shown in the workflow above), not to a tag of any kind.
  • Relying on the SSH client’s default behavior for authentication and host-key checking instead of explicitly loading a scoped deploy key and pinning the server’s host key. Letting a step silently fall back to an unconfigured client — or, worse, disabling host-key checking to make a connection “just work” — removes the server-identity guarantee SSH is meant to provide.
  • Letting a TAP check pass on an empty or truncated result file. A bare grep -q '^not ok' reports success on a file with zero lines, not just on a file with all-passing tests — validate the TAP plan count and result-line count before trusting the absence of not ok as a pass.
  • Forgetting that “Bob” and “TOBi” are the same project when searching for help or documentation — community posts, Stack Overflow answers, and some existing articles predate the rename.

FAQ

Can the GitHub Actions runner itself be an IBM i partition?

Yes, in principle — GitHub’s self-hosted runner distributions target specific OS/architecture combinations, and whether a supported runner binary exists for your specific PASE/IBM i environment should be checked against GitHub’s current supported-platforms documentation before attempting it. This article uses the SSH-from-a-separate-runner pattern specifically to avoid depending on that.

Is Bob still a valid name to search for?

The underlying project renamed itself to TOBi (The Object Builder for i) in 2025, per its own GitHub repository, which still carries the ibmi-bob repository name. Older material calling it “Bob” describes the same tool.

Does RURUN’s TAP output work the same way here as in a Jenkins pipeline?

Yes — TAP is a plain text format (ok/not ok lines) independent of the CI platform; only how each platform consumes that file differs (a Jenkins plugin versus a grep step failing the job directly, as shown above).

Why gate promotion with a GitHub Environment instead of just a workflow condition?

A workflow if: condition decides automatically; a GitHub Environment with required reviewers pauses the job for an explicit human approval. For moving compiled RPG objects into a shared library, that human checkpoint is the point — this article intentionally does not try to fully automate past it.

References

  • GitHub Docs: using self-hosted runners in a workflow — the default labels applied to a self-hosted runner (self-hosted, one OS label, one architecture label); the runs-on: [self-hosted, linux, ARM64] list syntax and the rule that a runner must match every listed label; the runs-on: { group: ... } and combined group-plus-label syntax for runner groups.
  • GitHub Docs: security hardening for GitHub Actions — that a tag reference (including a major-version tag) “can be moved or deleted if a bad actor gains access to the repository storing the action,” and that the documented mitigation is to “pin references to actions to a commit SHA,” with a dependency lockfile as the preferred alternative where supported. This is the basis for pinning actions/checkout and actions/upload-artifact to a full-length commit SHA in the workflow above, and for the “Pinning actions” section’s explanation of why @v4 alone is not a pin.
  • GitHub’s REST API tag references for actions/checkout and actions/upload-artifact — the exact full-length commit SHAs used in the workflow above (11bd71901bbe5b1630ceea73d27597364c9af683 for checkout@v4.2.2; ea165f8d65b6e75b540449e92b4886f43607fa02 for upload-artifact@v4.6.2), each independently cross-checked against the corresponding GitHub release page before use.
  • IBM/ibmi-bob on GitHub (the build tool’s own repository) — the project was “known as Better Object Builder, or Bob, until 2025” and is now named TOBi (The Object Builder for i); the build engine is GNU Make, with dependencies declared via standard makefile syntax; the tool “only compiles objects that need recompiling”; an IDE integration exists via the IBM Project Explorer VS Code extension. The exact makei command-line subcommand syntax is not confirmed here — the project’s dedicated documentation site renders its content client-side and could not be retrieved as readable text during research, so command syntax beyond the general build model is marked NOT TESTED throughout this article.
  • Reused from existing AS400Decoded content, not re-verified independently here: the RPGUnit RURUN ... OUTPUT(*TAP) syntax and TAP output format, as established in RPG Unit Testing with RPGUnit in 2026.

A third-party ibmi-ci npm package’s documented example (not independently verified further) was used only to confirm that driving IBM i builds over SSH from a separate CI host is an established pattern, not one invented for this article.

Not independently confirmed: the exact current makei CLI subcommands and flags; whether a GitHub-distributed self-hosted runner binary exists for native execution inside IBM i PASE; the iproj.json/Rules.mk examples shown (illustrative, not built or run); the rsync/ssh shell steps in the workflow, including the ssh-agent key-loading and known_hosts pinning steps and the TAP-validation script (illustrative shell syntax, not run against a live IBM i partition or a live GitHub Actions runner).

Internal links

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top