Using or interested in CircleCI for your continous integration needs, and interested in supporting the IBM Z (s390x) architecture in your open source project? You came to the right place! The following tutorial will help you through the documentation available for these runners in order to get you going with tests on an s390x native virtual machine, free of charge.

The CircleCI Self-Hosted Machine Runner binary has been made available for IBM Z (s390x) and Power (ppc64le) architectures. If you're already very familiar with CircleCI and setting up machine runners, the process should be familiar to you and you can get started now by visiting the documentation: Installing self-hosted runners with the web app. No cost access to a virtual machine on the IBM Z architecture for testing can be gained through an account on the IBM LinuxONE Community Cloud.

If you're new to machine runners or CircleCI itself, this tutorial will guide you through the steps of setting up CircleCI, getting the machine runner set up on a Red Hat Enterprise Linux 9 virtual machine in the LinuxONE Community Cloud, and writing your first tests with a simple application written in Go.

For this tutorial, you’ll want to have a GitHub account (or Bitbucket or GitLab) that you control where you can authorize the use of CircleCI and create a repository that we'll use for testing.

Step 1: Create a CircleCI account

Go to the CircleCI Signup page and create an account. The account is free of charge and will get you access to using their library of containers for tests, and the integrated dashboard where all of your tests will show up.

Step 2: Create your repository on GitHub

If you wish to match this tutorial exactly, use the name "hello" for the repository, and then add the following 3 files to your Git repository.

• hello.go (the code you’re testing)
• hello_test.go (the test against your code)
• .circleci/config.yaml (the CircleCI configuration we’re starting with)

hello.go:

package main

import "fmt"

func Hello() string {
	return "Hello, world"
}

func main() {
	fmt.Println(Hello())
}

hello_test.go:

package main

import "testing"

func TestHello(t *testing.T) {
	got := Hello()
	want := "Hello, world"

	if got != want {
		t.Errorf("got %q want %q", got, want)
	}
}

.circleci/config.yml:

version: 2.1

# Define a job to be invoked later in a workflow.
jobs:
  build:
    working_directory: ~/repo
    docker:
      - image: cimg/go:1.15.8
    steps:
      - checkout
      - run:
          name: Run tests
          command: |
            mkdir -p /tmp/test-reports
            gotestsum --junitfile /tmp/test-reports/unit-tests.xml
      - store_test_results:
          path: /tmp/test-reports

# Invoke jobs via workflows
workflows:
  functional:
    jobs:
      - build

We're using the simplest test with Go that I could come up with, Hello, world. Of course if you already have a project you wish to test, you can modify this tutorial to fit your needs.

Step 3: Connect your Git repository or account to CircleCI

Full documentation for connecting your Git repository to your CircleCI dashboard can be found in the GitHub integration overview, but essentially you want to use the menu in the top left hand side of your CircleCI dashboard and select “Create New Organization” and then select “Connect” on the GitHub section, then follow the instructions that take you to the GitHub website.

Rather use GitLab or Bitbucket? Go for it!

Warning: Be sure to review the permissions carefully. In order to integrate with a code repository to manage testing, currently CircleCI requires a decent amount of access. You’ll want to make sure this is acceptable to you, and any organization you’re working with. You can revoke access via GitHub at any time.

Step 4: Connect your project

Once connected, go to Projects in the left hand menu and select the repository you want to start testing with by clicking on “Set Up Project”. As mentioned earlier, for this example, I have put my Go code in a repository called “hello” so my references moving forward will use that.

Since this repository has a .circleci/ directory in it, you’ll see tests begin to run as soon as it’s connected. The test should pass and you will see something similar to the following:

Congratulations! You’ve now tested code with CircleCI. This initial example uses a hosted, containerized x86 environment provided by CircleCI. We now want to move forward with setting up testing for s390x.

Step 5: Set up your s390x Linux VM

If you don’t have access to an s390x VM in your own environment, you can one by signing up for the IBM LinuxONE Community Cloud.

Once you have an account, you’ll want to launch a Red Hat Enterprise Linux 9 virtual machine. For a step-by-step guide on how to do this and gain access, follow the latest instructions for setting up your virtual server.

Step 6: Install the CircleCI self-hosted machine runner

You'll probably want to read a bit about what the runner does and follow the instructions in the Machine Runner installation documentation. But before you begin, the following are a few things to keep in mind:

• There is no Container Runner for s390x today, just the Machine Runner, so make sure you use the Machine Runner Web App Installation instructions for Linux (https://circleci.com/docs/runner-installation-linux/) (and there is not currently a CircleCI CLI build for s390x, so configuration should be done through the Web App)
• When you get to the launch script step, make sure you download the launch script for Linux s390x (not amd64): export platform=linux/s390x && sh ./download-launch-agent.sh
• Follow the instructions for RHEL, since that’s the Linux distribution we're using

One of the steps has you create a custom Resource Class, which is your namespace NAME, followed by an identifier like “s390x_rhel91”. When you get to adding to your config.yml on the “Add Self-Hosted Runner to a Project” screen, you’ll want to add the following under the jobs: section in your .circleci/config.yml GitHub (and be sure to replace the NAME with your namespace, followed by the identifier you used):

s390x-build:
  machine: true
    resource_class: NAME/s390x_rhel91
    steps:
      - checkout
      - run:
          name: Install requirements
          command: |
            go mod init hello
            go install gotest.tools/gotestsum@latest
      - run:
          name: Run tests
          command: |
            mkdir -p /tmp/test-reports
            ~/go/bin/gotestsum --junitfile /tmp/test-reports/unit-tests.xml
      - store_test_results:
          path: /tmp/test-reports

And then in workflows: under jobs: you’ll want to run the s390x job alongside the existing job which was just called “build” so it will look something like this:

# Invoke jobs via workflows
workflows:
  functional:
    jobs:
      - build
      - s390x-build

Once you commit your changes, you should see your first job run on your s390x machine runner:

Congratulations!

In summary, we created a simple Hello World program in Go and tested it using a default image in CircleCI's container-based hosted testing infrastructure on x86_64. Then we added our own s390x-based virtual machine with a self-hosted CircleCI machine runner to run the same test.

If you're the maintainer of an open source project that's looking for more CI permanent resources for s390x than what are offered through the IBM LinuxONE Community Cloud, you may fill out the form here to apply for resources from the Open Source Software program: IBM LinuxONE Open Source Cloud Virtual Machine(s) Request Form