Preparing the GitHub Workflow

To trigger a workflow in GitHub CI/CD, a special yml script to invoke the container must be inserted into the project’s repository. This script MUST be placed in the .github directory at the top level of the repository. If it is not already present, a subdirectory named workflows must be created. Then, within the workflows directory, a yml script describing the bahviour of the workflow is placed. This script is triggered upon events specified in the script.

OpenRefactory supplies a sample script for use with GitHub CI/CD. It triggers upon the occurrence of push or pull requests but the DevOps engineer preparing the workflow can create whatever triggers are appropriate for their specific needs. This script can be incorporated into a previous workflow script or edited to make the workflow operate as needed.

We won’t cover how to add a file to a GitHub repository as that is beyond the scope of this User Guide.

For our example, we are using the baritone project. We go to the main repository page for this project and look at the .github/workflows directory:

We have copied the sample githubAction.yml script there. Let’s quickly review the sample script:

# This is a basic workflow to help you get started with iCR CI/CD
# If using GitHub Enterprise, this example will use _ge.openrefactory.com_ as the sample URL
name: Openrefactory_CI

# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the "master" branch
  push:
    branches: [ "master" ]
    
env:
  # Use this as the REGISTRY if you are using GitHub cloud. This sample script defaults to GitHub cloud
  REGISTRY: ghcr.io

  # Use this as the REGISTRY if you are using GitHub Enterprise
  # Substitute <geopenrefactory.com> with your Enterprise URL
  #REGISTRY: docker.ge.openrefactory.com 

jobs:
  OR_JOB:
    runs-on: ubuntu-18.04 # Or you can use ubuntu-latest
    # If you are using GitHub Enterprise, please substitute <self-hosted> with your Enterprise runner name
    #runs-on: <self-hosted>
    container:
            # Use this as the image if you are using GitHub cloud
            # This sample script defaults to GitHub cloud. Substitute the Users login ID for <User_ID>
            image: ghcr.io/<User_ID>/icr-github:latest

            # Use this as the image if you are using GitHub Enterprise
            # Substitute <ge.openrefactory.com> with your Enterprise URL
            #image: docker.ge.openrefactory.com/<User_ID>/Project_Name/icr-github:latest
            
    steps:
      # Comment out this line below if you are using GitHub Enterprise
      - uses: actions/checkout@v2
      - name: orjob
        run: |
          /workspace/configure_run.sh ${{ github.ref_name }} \
          ${{ github.repositoryUrl }} \
          ${{ secrets.ICR_URL }} \
          ${{ secrets.ICR_PASSPHRASE }} \
          ${{ secrets.PERSONAL_ACCESS_TOKEN }} \
          ${{ secrets.MAIL_ADDRESS }} \
          ${{ secrets.LANGUAGE_VERSION }} 
        shell: bash

In this sample script, the on: section specifies what will trigger the execution of this script. In this example, whenever a commit is pushed to the master branch, it will be executed. The registry where the package is registered is identified as ghcr.io as specified in the GitHub documentation. If you are using GitHub Enterprise, then the registry will be the URL of your local GitHub Enterprise server. For items such as the User ID for the user for whom this workflow is to be executed, subsitute <User_ID> with that User's login ID.

The critical items of interest are the variables referenced in the run: step. They are needed to be able to locate the targeted iCR server and to provide the Navigator with the information required so it can authenticate itself with the proper username and identify the project and branch name.

There are seven variables in the script. Let’s look at all of them. They are broken into 2 groups: preconfigured environment variables and user supplied secret values.