Automating build/deploy CI/CD with GitHub Actions
Last Updated
A version of this article appeared on viget.com
![Carpentry: an automatic lathe in plan and elevations, with examples of finished turning. Engraving by N. L. Rousseau after Gallet](/posts/automating-build-deploy-ci-cd-with-github-actions/GF68K3xqFN-896.jpeg)
Projects hosted on GitHub can implement continuous integration (CI), continuous deployment (CD), and continuous delivery (the other CD) with GitHub Actions workflows. This works in public and private repos. (There are tiered limits for storage and time.)
In this article we will look at the basic structure of GitHub Actions workflows, and then build out support to test all branches and then deploy production builds to a remote server via FTP. No GitHub Actions background is necessary, but a basic understanding YAML will be helpful.
(Why deploy via FTP? In my case, I needed to deploy a static generated Nuxt app to production. Using a service like Netlify or Vercel was not an option, and I had FTP access to the server but not SSH access (I hope you aren’t in the same situation). But the FTP part of this is just a small detail; the final deploy workflow is flexible and can be adapted to your needs.)
Goal
The goal is to build every branch when it is pushed, and to deploy the trunk branch when it builds successfully.
To get there with GitHub Actions we’ll use two workflows: one which builds, and one which builds and then deploys. They will have these features:
- The “build” (continuous integration, for features) workflow runs when any branch other than the trunk is pushed
- The “build” workflow caches Node dependencies, a performance optimization that can speed up the build job.
- The “build and then deploy” (continuous integration and continuous deployment, for production) workflow runs when the trunk branch is pushed
- The “build and then deploy” workflow’s deploy job runs only if the build step passes. This prevents bugs from being deployed.
- The “build and then deploy” workflow’s build job calls the “build” workflow. This makes the setup easier to maintain— the build job is written once, and used everywhere.
- The “build and then deploy” workflow’s deploy job deploys an artifact produced by the build step.*
* In GitHub Actions, using an artifact from one job in another requires uploading the artifact to GitHub as a file. The file is available for download after the workflow completes (by default for 90 days). That means that even though supporting manual continuous delivery at an arbitrary time is not a goal of the solution we’ll build, we do get pretty close to it by continuously delivering the built artifact to the continuous deployment workflow; if continuous delivery separate from automated deployment is a goal of yours, this file will be useful: where I have “build” and “build and deploy” workflows and configure the file to live just long enough for automated deployment, use just a “build” workflow and configure it to live as long as your process requires.
Concept
Let’s look at annotated barebones workflows. These are missing build and deploy steps, but they illustrate the structure. Working examples come next.
Build workflow
- Runs when called from another workflow
- Runs when any branch other than
main
is pushed - Runs on Linux
- Caches Node dependencies
- If the build steps are successful, uploads a build artifact
yaml
name: buildon:# support calling this workflow from other workflows# https://docs.github.com/en/actions/learn-github-actions/reusing-workflows#creating-a-reusable-workflowworkflow_call:# support running this workflow on push events# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#onpushpull_requestbranchestagspush:# run this workflow when pushing any branch other than mainbranches-ignore: mainjobs:build:# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idruns-onruns-on: ubuntu-latest# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepssteps:# build steps go here# - name: My first build step# …- name: Upload artifact# https://github.com/actions/upload-artifactuses: actions/upload-artifact@v2with:name: <the name>path: <the path># the artifact is only needed for the duration of the build-deploy workflow# adapt to your needs# https://github.com/actions/upload-artifact#retention-periodretention-days: 1
yaml
name: buildon:# support calling this workflow from other workflows# https://docs.github.com/en/actions/learn-github-actions/reusing-workflows#creating-a-reusable-workflowworkflow_call:# support running this workflow on push events# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#onpushpull_requestbranchestagspush:# run this workflow when pushing any branch other than mainbranches-ignore: mainjobs:build:# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idruns-onruns-on: ubuntu-latest# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepssteps:# build steps go here# - name: My first build step# …- name: Upload artifact# https://github.com/actions/upload-artifactuses: actions/upload-artifact@v2with:name: <the name>path: <the path># the artifact is only needed for the duration of the build-deploy workflow# adapt to your needs# https://github.com/actions/upload-artifact#retention-periodretention-days: 1
Build and deploy workflow
- When
main
is pushed, runs the “build” workflow’s build job. This code reuse makes our setup easier to maintain - If the build job succeeds, runs deploy steps
yaml
name: build-deployon:# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#onpushpull_requestbranchestagspush:# run this workflow when pushing mainbranches: mainjobs:use-build:# adapt to point to the current repo# https://docs.github.com/en/actions/learn-github-actions/reusing-workflows#calling-a-reusable-workflowuses: <owner>/<repo>/.github/workflows/build.yml@main# that's all - jobs that call a reusable workflow can do nothing elsedeploy:# only run the 'deploy' job if the 'use-build' job passes# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idneedsneeds: use-build# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idruns-onruns-on: ubuntu-latest# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepssteps:- name: Download use-build artifact# https://github.com/actions/download-artifactuses: actions/download-artifact@v2with:name: <the name>path: <the path># deploy steps go here# - name: My first deploy step# …
yaml
name: build-deployon:# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#onpushpull_requestbranchestagspush:# run this workflow when pushing mainbranches: mainjobs:use-build:# adapt to point to the current repo# https://docs.github.com/en/actions/learn-github-actions/reusing-workflows#calling-a-reusable-workflowuses: <owner>/<repo>/.github/workflows/build.yml@main# that's all - jobs that call a reusable workflow can do nothing elsedeploy:# only run the 'deploy' job if the 'use-build' job passes# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idneedsneeds: use-build# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idruns-onruns-on: ubuntu-latest# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepssteps:- name: Download use-build artifact# https://github.com/actions/download-artifactuses: actions/download-artifact@v2with:name: <the name>path: <the path># deploy steps go here# - name: My first deploy step# …
Working example
Now let’s see it for real, building a Node app and deploying it via FTP. (If you aren’t uploading via FTP, your deploy step(s) will be different.)
Build steps have been added to the build
workflow. Deploy steps have been added to the build-deploy
workflow.
yaml
name: buildon:# support calling this workflow from other workflows# https://docs.github.com/en/actions/learn-github-actions/reusing-workflows#creating-a-reusable-workflowworkflow_call:# support running this workflow on push events# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#onpushpull_requestbranchestagspush:branches-ignore: mainjobs:build:# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idruns-onruns-on: ubuntu-latest# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepssteps:# https://github.com/actions/checkout- name: Checkout# 2.4.0 was the latest at the time of writinguses: actions/checkout@v2.4.0# a standard step for GitHub actions on Node# https://github.com/actions/setup-node- name: Set up node env# 2.5.1 was the latest at the time of writinguses: actions/setup-node@v2.5.1with:# specify the version appropriate to your project# setup-node can also read the version from a Node version file. see the setup-node docs for detailsnode-version: 16.3.2# cache installed dependencies for best performance. yarn and pnpm are also supportedcache: npm- name: Install dependencies# For Node 16: https://docs.npmjs.com/cli/v8/commands/npm-ci# for other Node versions, look up the npm version at https://nodejs.org/en/download/releases/run: npm ci --prefer-offline --no-audit# lint steps, test steps, etc go here. adapt to your needs- name: Lintrun: npm run lint# build! adapt to your needs- name: Generaterun: npm run generate# upload the artifact for use in either CD# here, the 'dist' directory is compressed and uploaded to GitHub asset storage as 'build-artifact'- name: Upload artifact# https://github.com/actions/upload-artifactuses: actions/upload-artifact@v2with:# the name to save the compressed asset asname: build-artifact# the directory or file to upload. adapt to your needspath: dist# the artifact is only needed for the duration of the build-deploy workflow# adapt to your needs# https://github.com/actions/upload-artifact#retention-periodretention-days: 1
yaml
name: buildon:# support calling this workflow from other workflows# https://docs.github.com/en/actions/learn-github-actions/reusing-workflows#creating-a-reusable-workflowworkflow_call:# support running this workflow on push events# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#onpushpull_requestbranchestagspush:branches-ignore: mainjobs:build:# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idruns-onruns-on: ubuntu-latest# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepssteps:# https://github.com/actions/checkout- name: Checkout# 2.4.0 was the latest at the time of writinguses: actions/checkout@v2.4.0# a standard step for GitHub actions on Node# https://github.com/actions/setup-node- name: Set up node env# 2.5.1 was the latest at the time of writinguses: actions/setup-node@v2.5.1with:# specify the version appropriate to your project# setup-node can also read the version from a Node version file. see the setup-node docs for detailsnode-version: 16.3.2# cache installed dependencies for best performance. yarn and pnpm are also supportedcache: npm- name: Install dependencies# For Node 16: https://docs.npmjs.com/cli/v8/commands/npm-ci# for other Node versions, look up the npm version at https://nodejs.org/en/download/releases/run: npm ci --prefer-offline --no-audit# lint steps, test steps, etc go here. adapt to your needs- name: Lintrun: npm run lint# build! adapt to your needs- name: Generaterun: npm run generate# upload the artifact for use in either CD# here, the 'dist' directory is compressed and uploaded to GitHub asset storage as 'build-artifact'- name: Upload artifact# https://github.com/actions/upload-artifactuses: actions/upload-artifact@v2with:# the name to save the compressed asset asname: build-artifact# the directory or file to upload. adapt to your needspath: dist# the artifact is only needed for the duration of the build-deploy workflow# adapt to your needs# https://github.com/actions/upload-artifact#retention-periodretention-days: 1
yaml
name: build-deployon:# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#onpushpull_requestbranchestagspush:branches: mainjobs:use-build:# adapt to point to the current repo# https://docs.github.com/en/actions/using-workflows/reusing-workflows#calling-a-reusable-workflowuses: ./.github/workflows/build.yml# that's all - jobs that call a reusable workflow can do nothing elsedeploy:# only run the 'deploy' job if the 'use-build' job passes# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idneedsneeds: use-build# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idruns-onruns-on: ubuntu-latest# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepssteps:- name: Download build artifact# https://github.com/actions/download-artifactuses: actions/download-artifact@v2with:# the same name as used in the build workflowname: build-artifact# where to save the artifact# using the same path as in the build workflow "restores" the state from the end of the build workflowpath: dist# deploy! adapt to your needs.- name: Upload via FTP# https://github.com/marketplace/actions/ftp-action# 'with' config is specific to the 'sebastianpopp/ftp-action' actionuses: sebastianpopp/ftp-action@releases/v2with:host: $user: $password: $# use the same path as download-artifact downloaded the build artifact tolocalDir: dist# adapt to your needsremoteDir: html
yaml
name: build-deployon:# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#onpushpull_requestbranchestagspush:branches: mainjobs:use-build:# adapt to point to the current repo# https://docs.github.com/en/actions/using-workflows/reusing-workflows#calling-a-reusable-workflowuses: ./.github/workflows/build.yml# that's all - jobs that call a reusable workflow can do nothing elsedeploy:# only run the 'deploy' job if the 'use-build' job passes# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idneedsneeds: use-build# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idruns-onruns-on: ubuntu-latest# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepssteps:- name: Download build artifact# https://github.com/actions/download-artifactuses: actions/download-artifact@v2with:# the same name as used in the build workflowname: build-artifact# where to save the artifact# using the same path as in the build workflow "restores" the state from the end of the build workflowpath: dist# deploy! adapt to your needs.- name: Upload via FTP# https://github.com/marketplace/actions/ftp-action# 'with' config is specific to the 'sebastianpopp/ftp-action' actionuses: sebastianpopp/ftp-action@releases/v2with:host: $user: $password: $# use the same path as download-artifact downloaded the build artifact tolocalDir: dist# adapt to your needsremoteDir: html
Try it out
Make sure Actions are enabled in your GitHub repo: repo > Settings tab > Actions > “Allow all actions” or “Allow select actions”. Adapt the workflows to your needs, then commit them in a non-trunk branch and push to GitHub. Go to your GitHub repo’s Actions tab to see the build
workflow running. Merge into your trunk branch, push, and go to the Actions tab to see the build-deploy
workflow running.
Bonus
Every GitHub Actions workflow has a status badge at <workflow file path>/badge.svg
. To show the world that production is healthy, modify this snippet and add it to your README.md:
markdown
[![build-deploy workflow status badge](https://github.com/<owner>/<repo>/actions/workflows/build-deploy.yml/badge.svg)](https://github.com/<owner>/<repo>/actions/workflows/build-deploy.yml)
markdown
[![build-deploy workflow status badge](https://github.com/<owner>/<repo>/actions/workflows/build-deploy.yml/badge.svg)](https://github.com/<owner>/<repo>/actions/workflows/build-deploy.yml)
References
GitHub Actions documentation
- GitHub Docs > GitHub Actions > Learn GitHub Actions > Reusing workflows
- GitHub Docs > GitHub Actions > Learn GitHub Actions > Workflow syntax >
jobs..needs
- GitHub Docs > GitHub Actions > Learn GitHub Actions > Workflow syntax >
jobs..runs-on
- GitHub Docs > GitHub Actions > Learn GitHub Actions > Workflow syntax >
jobs..steps
- GitHub Docs > GitHub Actions > Learn GitHub Actions > Workflow syntax >
jobs..uses
- GitHub Docs > GitHub Actions > Learn GitHub Actions > Workflow syntax >
on..
Actions used
- cache action
- checkout action
- download-artifact action
- sebastianpopp/ftp-action action
- setup-node action
- upload-artifact action
Updates
March 25, 2024: Use “same repository” syntax for calling the build workflow from the build-deploy workflow.
Articles You Might Enjoy
-
-
Comparing Heroku, Netlify, Vercel, and GitHub Pages for Node.js Projects
Running popular web-based CD tools against each other
-