ibmi-ci

ibmi-ci is a command line tool to make it easier to work with IBM i from pipelines, like GitHub Actions, GitLab CICD, etc.

Installation

Install via npm:

npm i @ibm/ibmi-ci

Use in a GitHub Action

      - run: npm i -g @ibm/ibmi-ci
      - name: Deploy to IBM i
        run: | 
          ici \
            --cmd "mkdir -p './builds/ics_${GITHUB_HEAD_REF}'" \
            --rcwd "./builds/ics_${GITHUB_HEAD_REF}" \
            --push "." \
            --cmd "/QOpenSys/pkgs/bin/gmake BIN_LIB=CMPSYS"
        env:
          IBMI_HOST: ${{ secrets.IBMI_HOST }}
          IBMI_USER: ${{ secrets.IBMI_USER }}
          IBMI_PASSWORD: ${{ secrets.IBMI_PASSWORD }}
          IBMI_SSH_PORT: ${{ secrets.IBMI_SSH_PORT }}

How to use

After installation, run ici to see the help text and available parameters.

ibmi-ci is made up of steps and steps are built up from parameters, with the default step of connecting to the remote system, which always takes a place.

The steps ici will take is based on the parameters used on the CLI. For example:

ici \
  --rcwd "./builds/myproject" \
  --push "." \
  --cmd "/QOpenSys/pkgs/bin/gmake BIN_LIB=MYLIB"

This command will run 3 steps:

Set the remote working directory to ./builds/myproject
Upload the local working directory to the remote working directory (.)
Run a shell command

Default steps

By default, ibmi-ci will always:

Connect to the remote IBM i via SSH. Connection configuration is based on environment variables. Use ici to see more info.
Set the environment variables on the remote IBM i to those of the host runner (with some exceptions like SHELL, HOME, etc)

Ignoring errors

You can use a special ignore flag to suppress errors on certain steps: --ignore. This means if the following step errors, execution will continue nonetheless.

ici \
  --rcwd "./builds/myproject" \
  --push "." \
  --ignore --cl "CRTLIB $LIB"
  --cmd "/QOpenSys/pkgs/bin/gmake BIN_LIB=MYLIB"

Development

After cloning the repo, there are two options:

npm run local to install ici
Open in VS Code and debug

Todo ✅

Step for creating chroot automatically as the first step, or to specify which chroot to use
Ignore errors for certain steps. Sometimes we don't care if mkdir or CRTLIB failed.
Daemon mode so ici can be run multiple times but use the same connection