Deploying to OpenShift using GitHub Actions

The popularity of GitHub Actions is growing fast as they prove to be a simple, effective way to set up Continuous Integration (CI) and Continuous Delivery (CD) workflows. To help get your cloud-native projects built and deployed as easily as possible, we are releasing a collection of Red Hat GitHub Actions that facilitate setting up CI and CD pipelines for containerized applications.

The OpenShift starter workflow uses the Red Hat GitHub Actions to help you get an application up and running by providing a workflow that automatically builds and deploys your application. In this article, we'll do a brief overview of the actions, discuss the parts of your workflow we can simplify, and demonstrate how to quickly and easily get your application up and running on OpenShift.

 If you don't have access to an OpenShift cluster, check out https://www.openshift.com/try for a trial, or sign up for the new Developer Sandbox for Red Hat OpenShift. You can also run it locally with CodeReady Containers.

The Red Hat Actions

Red Hat Actions are available on the Actions Marketplace.

The first two actions are intended to be used only in workflows which interact with an OpenShift cluster.

1. oc-installer installs the OpenShift Client (oc) into your GitHub Action runner. Note that the GitHub provided Linux runners already come bundled with oc 4.6.
2. oc-login logs into an OpenShift cluster and sets up a Kubernetes config for the rest of the workflow job. After this action runs, oc and kubectl commands can be executed against the cluster.

The next three actions can be used to build and publish container images for any cloud platform, not just OpenShift.

1. buildah-build builds container images using buildah, which creates images from a base image for your application's runtime or from a Dockerfile.
2. s2i-build builds container images using source-to-image, which works by injecting source code into a base image for the application's runtime. No Dockerfile necessary.
3. push-to-registry pushes a container image to a container image registry such as quay.io, Dockerhub, the GitHub Container Registry, or an OpenShift Integrated Registry.

A workflow for a containerized application

Every CI/CD workflow is specific to its own project. While there are similarities between projects using the same tools (eg. Java applications built with Maven), there will always be adjustments required when writing a new workflow.

The Red Hat Actions are built using convention over configuration, which means they require a minimal amount of configuration, while allowing you to override the settings you need.

Below is a simplified CI/CD workflow for a containerized project. One might consider steps 1-5 to fall under CI, while 6 and 7 are CD.

1. Checkout the source code. This could be from the repository's upstream branch, or from a contributor's pull request.
2. Install build and runtime dependencies.
3. Compile the source code, if applicable.
4. Build the application artifact. For example, a jar archive, a JavaScript bundle, or a stand-alone executable.
5. Build the container image or images.
   • Here, we use buildah-build, or s2i-build.
6. Publish the latest image so it can be pulled for testing.
   • push-to-registry does just this.
7. Deploy the latest version of the application somewhere it can be tested and experimented with.
   • If you're deploying to OpenShift, use oc-login to set up the Kubernetes configuration and context.
   • Depending on your environment, you may need oc-installer too.

Your project should already have its own version of steps 2-4. The Red Hat Actions are designed to make steps 5-7 as easy as possible, whether or not your application is already containerized.

The starter workflow

GitHub Actions Starter Workflows are template workflows that can be added to your project with a few clicks. Developers can then edit and expand the starter workflow to fit their project's needs. We contributed an OpenShift starter workflow which builds a project from a Dockerfile, deploys it to OpenShift, and exposes it to the Internet.

Our default starter workflow requires a Dockerfile since it minimizes the number of changes that have to be made to the workflow file. Essentially, we expect the Dockerfile to build the application so we can focus on the image build, push, and deploy steps. If you do not have a Dockerfile, you can edit the build step to build from scratch, or to use s2i-build. See our spring-petclinic workflows for examples of building from scratch, and building using s2i.

The starter workflow uses buildah-build to build the application image from the Dockerfile, push-to-registry to push the image to an online registry, and oc-login to log into the cluster. The application is deployed using “oc new app”, and a Route is created with “oc expose” to make the application accessible from the internet.

View the OpenShift starter workflow in the starter-workflows repository.

In the short video below, I add the OpenShift starter workflow to an Express Hello World project. Adding the workflow and the necessary configuration takes just over a minute. One build later, and the application is up and running.

Deploying my Express in TypeScript starter project to OpenShift using the OpenShift starter workflow.

The best part is that the workflow automates your CI and CD so that subsequent pushes will update the application in place, so it's kept up-to-date at the same URL. In minutes, we've set up a bare-bones CD system. You can easily replace our simple deployment script with your own to perform a Helm install, Kustomize build, or any other method your project uses.

What's next?

If you want to start from a minimal workflow and incrementally add steps, the starter workflow is perfect. Follow the video above to give the starter workflow a try.

If you're interested in a more sophisticated workflow that uses our actions, check out the spring-petclinic example.

As always, we encourage community participation. Please don't be shy about opening any GitHub issues or feature requests. If you have an idea for an action you would like to see, or notice something absent from the ones we have, let me know in an issue, a comment here, or an email.