Menu

DevOps on IBM i

Using Git and TOBi on IBM i: A Practical Deployment Flow

A practical way to think about Git, TOBi, branch strategy, environment builds, deployment automation, rollback planning, and IBM i-friendly DevOps.

IBM iGitTOBiDevOpsDeploymentRPGSQLRPGLE

Git on IBM i is not just about moving source code into a repository. The real value starts when Git becomes part of a controlled development, promotion, build, deployment, and rollback process.

Diagram showing Git branches flowing from feature branch to dev, uat, and main, with deployment automation, environment files, TOBi build, and production stable rollback reference

A practical IBM i deployment flow should connect Git branches, environment configuration, TOBi builds, and production rollback planning.

For IBM i teams, DevOps cannot be treated as a simple copy of what works on other platforms.

IBM i has its own realities: libraries, objects, source members, compile order, job descriptions, library lists, service programs, binding directories, database objects, commands, display files, printer files, authorities, and environment-specific runtime behavior.

That does not make DevOps harder for the sake of being harder.

It means IBM i DevOps needs to be designed with the platform in mind.

Git is valuable on IBM i, but Git by itself is not the solution.
The solution is a controlled flow from development to test to production.

Key idea

A good IBM i DevOps flow should not try to make IBM i look like every other platform. It should make IBM i delivery safer, more traceable, more repeatable, and easier to understand.

Who this article is for

This article is for IBM i developers, technical leads, architects, and teams who are asking questions like:

If your team is still moving source manually, compiling directly in target libraries, relying on memory for promotion steps, or struggling to understand what changed between environments, this article is for you.

What this flow is trying to solve

Many IBM i teams do not have a source control problem only.

They have a delivery control problem.

The risks usually show up in places like:

Git helps with some of this.

TOBi helps with some of this.

Deployment automation helps with some of this.

But the real improvement comes when these pieces are connected into one flow.

Why Git on IBM i needs structure

Many teams start with Git by asking a simple question:

How do we store RPG source in Git?

That is a good first step, but it is not enough.

The bigger question is:

How do we safely move IBM i changes from development to test to production?

That question is more important because the real risk is usually not source storage. The real risk is uncontrolled promotion, manual deployment, missing compile steps, wrong library lists, inconsistent environments, unclear rollback plans, and production changes that are hard to trace.

A practical Git strategy for IBM i should help answer:

That is where Git becomes more than a source repository.

It becomes part of an engineering process.

A simple branch model

A practical IBM i Git strategy should start simple.

For many teams, this branch model is enough:

dev   → development environment
uat   → user acceptance / test environment
main  → production-ready code

The promotion path becomes:

feature branch
      ↓
dev
      ↓
uat
      ↓
main

Each branch should represent a different level of confidence.

The dev branch is where active work is integrated and tested by developers.

The uat branch is where changes are promoted for user acceptance testing, QA validation, or business review.

The main branch should represent production-ready code.

Keep the branch model simple at first.

A clear promotion flow that the team actually follows is better than a complicated branching strategy that looks good on paper but fails in daily use.

Feature branches still matter

Even with a simple dev, uat, and main model, developers should usually work in feature branches.

For example:

feature/customer-api-validation
feature/invoice-date-fix
feature/journal-monitoring-alerts
bugfix/null-merge-handling

A developer works in a feature branch, tests the change, and then merges into dev.

That gives the team a cleaner separation between:

The flow becomes:

feature branch
      ↓
merge to dev
      ↓
deploy to development
      ↓
promote to uat
      ↓
deploy to UAT
      ↓
promote to main
      ↓
deploy to production

This is simple enough to understand, but structured enough to reduce confusion.

Why direct production changes should be avoided

On IBM i, it can be tempting to fix something quickly by compiling directly into a production library.

Many teams have done this because the platform makes it easy.

But easy does not always mean safe.

Direct production changes create problems:

A Git-based flow should reduce these situations.

Production should be updated through a known path:

dev → uat → main → production

Emergency fixes can still exist, but they should also be brought back into the Git flow as quickly as possible.

Mapping branches to environments

A useful IBM i deployment flow should know which environment to deploy to based on the branch.

For example:

dev   → DEV libraries
uat   → UAT libraries
main  → PROD libraries

The deployment process can detect the branch and load the correct configuration.

Conceptually:

Git branch changed
      ↓
Determine target environment
      ↓
Load environment configuration
      ↓
Run build
      ↓
Deploy objects

This keeps the process consistent.

Developers do not need to manually remember which library to compile into. The branch and environment configuration should drive that decision.

Environment-specific configuration

On IBM i, environment configuration matters.

A program compiled in the wrong library, with the wrong library list, or against the wrong database library can create serious problems.

A practical setup may use environment files like:

.env.dev
.env.uat
.env.prod

Each file can define values such as:

OBJLIB=MYAPPDEV
DBLIB=MYDBDEV
CURLIB=MYAPPDEV
LIBLIST=MYAPPDEV,MYDBDEV,COMMONLIB

The deployment script can map branches to files:

dev   → .env.dev
uat   → .env.uat
main  → .env.prod

The exact format is less important than the principle:

Environment-specific values should be controlled, repeatable, and visible.

They should not live only in someone’s memory.

Example environment setup

A development environment file may look like this:

OBJLIB=MYAPPDEV
DBLIB=MYDBDEV
CURLIB=MYAPPDEV
LIBLIST=MYAPPDEV,MYDBDEV,MYCOMMON

A UAT file may look like this:

OBJLIB=MYAPPUAT
DBLIB=MYDBUAT
CURLIB=MYAPPUAT
LIBLIST=MYAPPUAT,MYDBUAT,MYCOMMON

A production file may look like this:

OBJLIB=MYAPPPROD
DBLIB=MYDBPROD
CURLIB=MYAPPPROD
LIBLIST=MYAPPPROD,MYDBPROD,MYCOMMON

This makes the environment differences explicit.

When a build runs, the deployment process knows which values to use based on the branch being deployed.

Be careful with library lists

Library lists are powerful, but they can also create confusion.

The same program may compile successfully in one environment and fail in another because the library list is different.

The same program may run differently because it finds a different file, service program, data area, job description, or command earlier in the library list.

That is why the deployment flow should make the library list intentional.

A good process should answer:

IBM i DevOps should not ignore library lists.

It should make them visible and controlled.

Suggested repository structure

Every team will organize source differently, but a simple starting structure may look like this:

my-ibmi-app/
  .env.dev
  .env.uat
  .env.prod

  iproj.json
  Rules.mk

  src/
    qrpglesrc/
      CUSTAPI.rpgle
      INVPROC.sqlrpgle

    qclsrc/
      BUILDALL.clle
      STRAPP.clle

    qddssrc/
      CUSTDSP.dspf

    qsqlsrc/
      tables/
        CUSTOMER.sql
        INVOICE.sql

      views/
        CUSTOMER_ACTIVE.sql

      migrations/
        20260706_add_invoice_status.sql
        20260708_alter_customer_key.sql

  scripts/
    deploy.sh
    rollback.sh

This is only an example.

Some teams may organize by object type. Others may organize by feature, application module, or business area.

The key is consistency.

A good repository structure should make it easy to understand:

The structure should help the team, not just satisfy a tool.

Where TOBi fits

Git and TOBi solve different parts of the problem.

Git helps the team manage source code, history, branching, reviews, and promotion.

TOBi helps organize and run repeatable IBM i builds.

The deployment script connects the two.

Git tracks the source
      ↓
Deployment script prepares the environment
      ↓
TOBi runs the IBM i build
      ↓
Objects are created or updated
      ↓
Build result is logged

That connection is where the real value starts.

Without a build process, Git may only become a place where source is stored.

With a repeatable build process, Git becomes part of controlled delivery.

The build is not just a compile

On IBM i, a build can mean much more than compiling one RPG program.

A build may include:

That is why the build process should be intentional.

A manual compile may work for one small change, but it becomes risky when multiple objects, dependencies, environments, and teams are involved.

A repeatable build process helps reduce uncertainty.

The goal of the build process is repeatability.

The same source, built through the same process, should produce predictable results in development, UAT, and production.

A practical build flow

A practical Git and TOBi flow may look like this:

1. Developer pushes or merges code.
2. Deployment process detects the branch.
3. Branch is mapped to an environment.
4. Environment values are loaded.
5. Working copy is updated.
6. TOBi build is executed.
7. Build output is captured.
8. Success or failure is logged.
9. Production stable reference is updated only after deployment and release checks pass.

This does not need to be perfect on day one.

The first goal is to make the process visible and repeatable.

Deployment automation

Without automation, Git can become only a source archive.

The bigger improvement comes when a push or merge triggers a controlled process.

A deployment script can:

A simplified flow may look like this:

Push or merge occurs
      ↓
Deployment script receives branch name
      ↓
Branch is mapped to environment
      ↓
Working directory is updated
      ↓
Environment file is loaded
      ↓
TOBi build runs
      ↓
Result is logged

This gives the team a predictable path.

The goal is not to make deployment complex.

The goal is to remove manual guesswork.

Example branch-to-environment logic

The deployment script can start with very simple branch mapping.

For example:

case "$BRANCH" in
  dev)
    ENV_FILE=".env.dev"
    TARGET_ENV="DEV"
    ;;

  uat)
    ENV_FILE=".env.uat"
    TARGET_ENV="UAT"
    ;;

  main)
    ENV_FILE=".env.prod"
    TARGET_ENV="PROD"
    ;;

  *)
    echo "No deployment configured for branch: $BRANCH"
    exit 0
    ;;
esac

This is not the full deployment script.

It is the core idea.

The branch should drive the environment. The environment should drive the build configuration.

Loading the environment

Once the environment file is selected, the deployment process should load it intentionally.

Conceptually:

if [ ! -f "$ENV_FILE" ]; then
  echo "Environment file not found: $ENV_FILE"
  exit 1
fi

set -a
. "./$ENV_FILE"
set +a

After this, the build process can use values like:

OBJLIB
DBLIB
CURLIB
LIBLIST

This avoids hard-coding environment-specific values directly in the deployment script.

Source only reviewed configuration files: the shell executes their contents. Keep passwords and tokens in the deployment environment’s secret store, not in these committed examples.

Exporting these names alone does not configure TOBi. Reference them in the project’s iproj.json, for example:

{
  "description": "Example application build",
  "objlib": "&OBJLIB",
  "curlib": "&CURLIB",
  "preUsrlibl": ["&DBLIB", "MYCOMMON"],
  "buildCommand": "makei build"
}

The illustrative LIBLIST variable above is a deployment-script convention, not an automatically applied TOBi setting. Map each required library into the documented project settings and review any directory-level .ibmi.json overrides. Confirm the resulting library list and target library in a development build before promotion.

It also makes it easier to review and adjust environment settings without rewriting deployment logic.

Running the TOBi build

After the environment is loaded, the deployment script can run the build.

Conceptually:

echo "Starting build for $TARGET_ENV"
echo "Object library: $OBJLIB"
echo "Database library: $DBLIB"

makei build

Or, depending on the environment and installation path, the build command may be fully qualified.

The exact command can vary by setup.

The important part is that the build command should be:

For example:

if makei build; then
  echo "Build succeeded for $TARGET_ENV"
else
  echo "Build failed for $TARGET_ENV"
  exit 1
fi

Build logs are not optional

Every deployment should leave evidence.

At minimum, the process should log:

Without logs, troubleshooting becomes guesswork.

A failed build should not result in only:

Build failed.

It should tell the team what failed, where, and during which deployment.

Do not hide failures

A deployment script should fail clearly.

If the environment file is missing, stop.

If the branch is not recognized, stop or skip intentionally.

If the build fails, stop.

If production rollback fails, report that clearly.

Silent failures are dangerous because they create false confidence.

A good deployment process should make success obvious and failure actionable.

What comes next

A Git and TOBi flow gives IBM i teams a stronger delivery foundation.

It helps connect source control, branch strategy, environment configuration, repeatable builds, deployment scripts, and build logs.

But production deployment needs extra care.

Production changes affect real users, scheduled jobs, integrations, database objects, reporting, batch windows, and business operations. That is why production protection, emergency fixes, rollback planning, and database changes deserve their own discussion.

Continue with IBM i Production Deployment: Protection, Rollback, and Release Safety for production controls, release validation, and recovery planning.

References

Documentation and supporting sources for this article.

Comments

Share your thoughts, questions, or real-world IBM i experiences related to this article.