Here is a common situation: You write your code, everything is on GitHub, and you are ready to publish it. But, you know that your job is not finished yet. You need to deploy your code and this process can be a nightmare at times.
Ideally, you should be able to do this whole process all in one place, but until now, you always had to set up external services and integrate them with GitHub (or add post-commit hooks). What if, instead, you could replace all of these extras and run everything directly from your GitHub repository with just a few YAML lines? Well, this is exactly what GitHub Actions are for.
GitHub Actions are a new feature recently introduced by GitHub. They enable users to set up custom software development life cycle (SDLC) workflows directly from their GitHub repositories. By using actions, developers can let GitHub take care of a number of processes that can be triggered by a variety of events on the platform, like pushing code, making a release, and so on. This way, you can let GitHub deploy your app every time an event occurs and just focus on your code.
Although GitHub Actions is still quite new, we could not wait to make an action and let developers connect and deploy to their Red Hat OpenShift cluster directly from their GitHub repository. In this article, we will take a quick look at the OpenShift Actions extension and show how easy it is to set up and use.
Note: OpenShift Actions can be downloaded from the GitHub marketplace directly from this link.
Using OpenShift Actions
To use OpenShift Actions in your GitHub repository, start by creating your workflow and saving it as a YAML file in .github/workflows/<file name>.yml. By clicking on the Actions tab (on top of your repository, next to Pull request) you will be shown the most popular continuous integration workflows and you will be guided to set up your own, as shown in Figure 1.
As you can see in the example below, you can define the events that trigger your workflow, the runner to execute each job (e.g., different types and versions of virtual host machines, including Linux, Windows, and macOS), and all of the actions to run:
name: CI
on:
# Trigger the workflow on push to the master branch
push:
branches:
- master
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: OpenShift Action
uses: redhat-developer/openshift-actions@v1.1
with:
version: 'latest'
openshift_server_url: ${{ secrets.OPENSHIFT_SERVER_URL }}
parameters: '{"apitoken": "${{ secrets.API_TOKEN }}", "acceptUntrustedCerts": "true"}'
cmd: |
'version'
'start-build nodejs-ex --follow'
'status'
In our example, we want to deploy our application on OpenShift every time something is pushed to our master. For this reason, we configure our workflow to start when the event push occurs and also specify the branch we are interested in, the master. If the branch is omitted, the workflow will trigger on each push made to the repository.
Next, we need to specify whether to use a GitHub-hosted or self-hosted runner. GitHub only provides runners on Windows Server 2019, Linux Ubuntu 16.04/18.04, and macOS Catalina 10.15. If you want to have your own runner on Red Hat Enterprise Linux/CentOS/Fedora, you have to choose self-hosted. Here is a list of all supported operating systems.
Finally, we need to set up all of the actions (steps) we want to execute. In this case, we are just deploying our application to our OpenShift cluster using our OpenShift action, but you could also add another action to send an email or an SMS to someone, or run tests. Just use your imagination.
Note: In this example, we are using OpenShift Actions v1.1. To use the latest release, go to the marketplace.
OpenShift action inputs
You can see that the OpenShift action requires inputs to run. Let’s look at what they are and what they are for:
version(optional): The version of theocCLI that we want the OpenShift Actions to use when executing commands. This input accepts three different values:- version number (i.e.,
3.11.36) - URL for downloading the oc bundle (i.e.,
https://mirror.openshift.com/pub/openshift-v3/clients/3.11.36/linux/oc.tar.gz) - version:
- Used in the form
version: 'latest'. - Downloads the latest version available.
- Acts as the default value for this input.
- Used in the form
- version number (i.e.,
openshift_server_url(required): The URL for the OpenShift cluster, used in the formopenshift_server_url: ${{ secrets.OPENSHIFT_SERVER_URL }}.parameters(required): A JSON string with the values needed to connect to the OpenShift cluster. Must be in the formparameters: '{"apitoken": "${{ secrets.API_TOKEN }}", "acceptUntrustedCerts": "true"}'.cmd(required): One or moreoccommands to be executed.
OpenShift action authentication
To allow the extension to connect to our cluster, we need to configure an OpenShift connection. The parameters input is used for this purpose. Based on its value, one of two supported authentication methods will be used: basic or token.
Basic authentication
The parameters input uses a username and password to connect to the cluster, i.e., parameters: '{"username": "${{ secrets.USERNAME }}", "password": "${{ secrets.PASSWORD }}", "acceptUntrustedCerts": "true"}'
| Name | Requirement | Description |
|---|---|---|
username |
required | The OpenShift username. |
password |
required | The password for the specified user. |
acceptUntrustedCerts |
optional | Whether it is ok to accept self-signed (untrusted) certificates. |
certificateAuthorityFile |
optional | The path to where the certificate authority file is stored. |
Token authentication
The parameters input uses an API token to connect to the cluster, i.e., parameters: '{"apitoken": "${{ secrets.API_TOKEN }}"}'.
| Name | Requirement | Description |
|---|---|---|
apitoken |
required | The API token used for authentication. |
acceptUntrustedCerts |
optional | Whether it is ok to accept self-signed (untrusted) certificate. |
certificateAuthorityFile |
optional | The path where the certificate authority file is stored. |
Secrets
As you can see above, we never write our sensitive data in the clear. We always use secrets. Even though this setup is not mandatory, we highly suggest using secrets when needed.
Secrets are encrypted environment variables created in a repository and are only used by GitHub Actions. GitHub encrypts secrets in the web browser using public key-authenticated encryption and the Poly1305 cipher algorithm. For more information, see the TweetNaCl.js documentation.
To make a secret available to an action, you must set it in your repository and then add it as an input or environment variable in the workflow file.
Note: For an organization's repository, you must have admin access in order to create encrypted secrets. For a user account repository, you must be the repository owner to create encrypted secrets.
Here is how to create a secret:
- Go to the main page of your repository.
- Click on Settings.
- In the left sidebar, select Secrets.
- Type a name for your secret in the Name input box. (Secret names must be unique and cannot contain any spaces.)
- Type the value for your secret. (To ensure that GitHub redacts your secret in logs, avoid using structured data as the values of secrets. Avoid creating secrets that contain JSON or encoded Git blobs.)
- Click Add secret.
Note: Your workflow can have up to 100 secrets.
Final words
At this point, you should be able to set up your workflow and see the OpenShift action running every time the event chosen in your YAML file is triggered. To check if your workflow is working properly, you can always visit the Actions tab in your repository and verify that all of the steps succeeded, as shown in Figure 2.
If you encounter any bugs, have any suggestions, or if you would like to have a new feature implemented, you can submit an issue through our repo. OpenShift Actions is an open source project and suggestions, comments, and pull requests are always welcome.
Last updated: June 29, 2020