Using GitHub Actions to Unlock GitOps Workflows with HashiCorp Waypoint
Warning
This content is part of the legacy version of Waypoint that is no longer actively maintained. For additional information on the new vision of Waypoint, check out this blog post and the HCP Waypoint documentation.
GitOps has become an increasingly popular method of shipping software. Thanks to tools like GitHub Actions, defining an automated GitOps workflow to take action based on your project’s git repository has never been easier than it is today! Whether you’re looking to automate deployments on-merge with your git repo, or are looking for a way to consciously deploy your application on an interval, GitOps deployments will give you a workflow defined through git to deliver your application.
This guide will lead you through setting up GitHub Actions to run a Waypoint pipeline on push to various Git branches, as well as configuring GH Actions to continuously deploy through a scheduled cron job.
Prerequisites
This guide assumes that you have already set up some kind of infrastructure to run a Waypoint Runner, HCP Waypoint access, or optionally a self-managed Waypoint server. We recommend either Kubernetes or HashiCorp Nomad for your infrastructure.
You will need an account on GitHub, as well as a Waypoint project committed to a Github repo. This is the repository we will use to write a GitHub action. If you don’t have a project yet, there are plenty of example Waypoint projects in the examples repository to get started with.
Setting Up Waypoint
HashiCorp provides a hosted version of Waypoint that runs the server on HCP. This guide supports using both a self-managed Waypoint server as well as HCP Waypoint. The main difference is what Waypoint server address you configure in your GitHub secrets which we will discuss in the next section. Follow the docs for installing your own self-managed Waypoint server, this guide will not go over setting it up.
If you are using HCP Waypoint, you’ll need to make sure you install a runner on your infrastructure so that Waypoint can run operations. On the platform where you will run your runner on your own infrastructure, you’ll want to configure your CLI context to talk to HCP Waypoint, and then install a runner into your managed infrastructure. Notice that the waypoint runner install commands will change depending on what platform you are installing to.
Take special note of WAYPOINT_TOKEN and WAYPOINT_SERVER_ADDR. We will be using those values as secrets in the next section for configuring GitHub Actions.
If you already have a Waypoint CLI context configured and runners installed, you can retrieve the server address and token values from your default CLI context. Found via waypoint context inspect
:
Waypoint and GitHub Actions
Setting up your own GitHub Action is as easy as defining an action config in the .github/workflows
folder of your project. Before we get to that, we’ll want to configure our git repo with a few secrets.
Configuring Your Waypoint Project For GitHub Actions
To use certain secrets within a GitHub action, we’ll want to figure our GitHub project with a few secrets:
WAYPOINT_SERVER_ADDR
: Waypoint Server AddressWAYPOINT_SERVER_TOKEN
: Waypoint Server Authentication Token
We will configure these secrets directly under Settings > Secrets > Actions.
Clicking New repository secret will bring up the window to add a new secret to use with our action. For example, our WAYPOINT_SERVER_ADDR secret:
Don’t forget to configure the Waypoint Authentication Token as well as another Action secret.
Note: Because the Waypoint server address and token are both parameterized, that means switching from a self-managed Waypoint server to HCP Waypoint is as simple as updating these values under your GitHub settings rather than having to reconfigure your GitHub Action script.
GitHub Action Yaml
Now that we’ve set up our GitHub repository to have a few secret variables, we can commit our Action config:
This config will automatically install the latest version of Waypoint from HashiCorp’s release repository. It uses the secrets we set up in GitHub via ${{ secret.SECRET_NAME }}
. Finally, for each run of a pipeline, we will run that operation in the specific workspace mapped to the git branch via -workspace=${{ github.ref_name }}
and if ran on the non-default branch, we will grab that commit for -remote-source=ref=$GITHUB_SHA
. You could also change this script to run waypoint up
.
Waypoint Deployments on Push
The GitHub action config above by default will run on push to these branches only:
- main
- prod
- test
That means when GitHub detects a push, the GitHub action will automatically run for those branches only. GitHub Actions has many different ways to configure how Actions run, so please read the documentation if you’d like your own action to behave differently!
We recommend setting up branch protections as well so that deployments aren’t accidentally pushed out without passing proper GitHub branch checks.
Based on the configuration, whenever you merge a pull request or push a commit to main
, prod
, or test
, the GitHub action we defined will be executed.
Deploying Your Application Continuously
GitHub actions can also be configured to run on a scheduled cron. At the time of writing this, scheduled jobs on GitHub Actions will only run on the default branch of the repository. This might be useful for making the main
branch the continuous integrated branch that deploys to your testing environment before it goes out to production.
To enable this, simply comment out the scheduled
key of our GitHub Action configuration.
Next Steps
- Continuously deployments on different branches
- https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
- Actions can be configured to only run on certain branches, with certain
ref
s. This is considered an advanced use-case and is not covered for this tutorial.
- GitHub Actions docs: https://docs.github.com/en/actions
- Try HCP Waypoint
- Waypoint Tetris on GitHub: https://github.com/briancain/waypoint-tetris