Authors: Rishika Kedia, Basavaraju G, Dilip B , Modassar Rana

Abstract:

The objective of this blog is to execute the GitHub Actions workflow on an IBM Z / IBM® LinuxONE (s390x) machine using a self-hosted runner on x86 machine. To accomplish this, we will establish an SSH connection from the x86 machine and then run the job on to IBM Z / IBM® LinuxONE (s390x).

Introduction

In the world of agile software development, efficiency and automation are key factors in achieving success. One tool that has gained immense popularity in recent years is GitHub Actions. This powerful feature offered by GitHub allows developers to automate their workflows, streamline processes, and enhance collaboration by automating code testing and integration within their projects.

Actions enable continuous integration (CI) and continuous deployment (CD) practices. This ensures that code changes are thoroughly tested before being merged into the main codebase, leading to higher code quality and more reliable software releases. GitHub Actions distinguishes itself by being fully hosted and managed by GitHub. This distinct advantage streamlines the initial setup process and ensures seamless scalability to meet your changing needs. However, GitHub Actions officially supports self-hosted runners only on x86 platform, it does not have official support for IBM Z / IBM® LinuxONE (s390x architecture) yet.

Pre-requisites:

• Need to have one Account in GitHub and IBM Cloud®.
• Create one Virtual Private Cloud (VPC) in IBM Cloud.
• Create SSH-key pair to login into virtual server.
• Create one x86 virtual server instance (VSI) that will act as bastion node.
• Configure bastion node as self-hosted runner.

To run CI jobs, we need an IBM Z / IBM® LinuxONE (s390x) virtual service instance for executing the GitHub Actions workflow in the same VPC. 

1.      Create s390x virtual server instance with UI: 

Step 1: Sign-in the IBM Cloud console  got to = menu icon -> VPC Infrastructure > Compute > Virtual server instances.

Step 2:  Click Create and begin entering virtual machine (VM) name and select CPU as IBMZ s390x and hosting type as public.

Step 3: Select an operating system for the instance. You can select an image, a snapshot of a boot volume, or an existing boot volume. 

Step 4:  Select profile, SSH keys, storage, and networking details by specifying the information in following table.

More Details about creating an s390x VSI, please refer to IBM Cloud VSI Creation.

2. Setup SSH Connection between x86 and s390x VM:

To establish a password less SSH connection between an x86 and s390x VM, we need to add the SSH keys of the x86 VM to the authorized keys file of the s390x VM. Follow these steps to generate SSH keys from the x86 VM if they don't already exist, using the ssh-keygen command:

• If you haven't already, access the x86 VM through a terminal or SSH client.
• Run the following command to generate SSH keys: ssh-keygen
• You will be prompted to provide a file name and passphrase for the SSH keys. Press Enter to accept the default file name and leave the passphrase blank for a key without a password.
• The ssh-keygen command will generate a public and private key pair. The public key will have the ".pub" extension and the private key will not be visible or accessible to others.
• Retrieve the generated public key by running the following command: cat ~/.ssh/id_rsa.pub
• The output will display the contents of the public key. Copy the entire content to the clipboard.
• Access the s390x VM either through a terminal or SSH client.
• Locate the authorized_keys file on the s390x VM. The file is typically located in the ~/.ssh/ directory.
• Edit the authorized_keys file and add the copied public key from the x86 VM as a new line.
• Save and close the authorized_keys file.
• Once you have completed these steps, the x86 VM's SSH keys will be added to the authorized_keys file of the s390x VM, allowing for a SSH connection without password between them.

3. Setup the GitHub repository 

 Create a new repository or simply fork repository into your GitHub account.

4 Create a GitHub secret in Repository for S390X VM IP

Sometimes we don’t want to expose IP address of the machines to outside world in the logs. So, we need to create secret to mask the IP Address. Follow this document to create secret in your GitHub account. Here we have created Secret name with S390X_VM_IP with IP_ADDRESS value of s390x VM. Now secret is securely stored within GitHub. It will be masked in logs and not exposed publicly.

To use the secret in out GitHub Actions workflow, you can reference it using the syntax {{secrets.S390x_VM_IP }}, where " S390x_VM_IP " is the name, you provided for the secret in step 5.

Step 5: Adding a self-hosted runner to a GitHub repository

Follow these instructions for adding a self-hosted runner to the GitHub repository on an x86 machine.

As you configure the self-hosted runner, the command line interface (CLI) will present a series of questions for you to answer. These questions will include assigning a name to the runner and specifying the output directory where job results will be stored. By providing these answers, you can customize the runner's settings to align with your specific requirements and preferences.

After setting up the configurations, now run run.sh on x86 VM to accept the jobs.

Now self-hosted runner on x86 is ready to accept the jobs.

6. Setting up the GitHub Actions workflow.

For the first time, we need to trigger a GitHub Actions workflow manually. You can follow these steps:

• Navigate to your GitHub repository where the workflow is defined.
• Click on the ‘Actions’ tab at the top of the repository.
• On the ‘Actions’ page, you will see a list of workflows. Find the workflow you want to trigger and click on the workflow's name.
• On the right side of the workflow page, click on the ‘Run workflow’ button.
• You may be prompted to provide any required inputs or parameters for the workflow. Fill in the necessary information, if applicable.
• Click on the ‘Run workflow’ button to manually trigger the workflow.
• The workflow will start running, and you can monitor its progress and view the logs on the ‘Actions’ page.

On subsequent workflows, once you have pushed any change to GitHub repository, GitHub Actions workflow will trigger automatically.

This script is ran on IBM Z / IBM® LinuxONE (s390x) VM, so you can update this script to have built and testing of repo.

References:

• Self-hosted runners
• IBM Cloud VPC
• Creating SSH keys