This guide will walk you through setting up a CI/CD pipeline using GitHub Actions. Our pipeline will build code, run unit tests, deploy to a container, and handle notifications and manual approvals. Additionally, we'll set up multi-environment deployments.
- Git and GitHub Account: Ensure you have Git installed and a GitHub account.
- Docker: Install Docker to manage containers.
- AWS Account (Optional): For deploying using AWS services like EKS, ECS, or Lambda.
Side note: This guide and demo will deploy to AWS, but this is not required for using CI/CD with github actions.
In order to understand the basics of GitHub actions, we will make a 'hello world' example, where on a simple push to the main branch will start an action with the title of the user that made the push.
- Go to GitHub and log in.
- Click on the + icon and select New repository.
- Name your repository, provide a description, and click Create repository.
For new github users, check out the GitHub documentation on repositories
- Clone your repository localy (GitHub documentation on cloning a repository)
- Step into the root of the repository. To make sure you are in the root, run
ls -a
and you should see a directory named.git
- Inside the directory
./.githubactions/workflows
, create a fileci-cd.yml
(Create both directories if necessary)
Inside the file created, copy the following code:
name: GitHub Actions Demo
run-name: ${{ github.actor }} is testing out GitHub Actions 🚀
on:
push:
branches:
- main
jobs:
Explore-GitHub-Actions:
runs-on: ubuntu-latest
steps:
- run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event."
- run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by GitHub!"
- run: echo "🔎 The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
- name: Check out repository code
uses: actions/checkout@v4
- run: echo "💡 The ${{ github.repository }} repository has been cloned to the runner."
- run: echo "🖥️ The workflow is now ready to test your code on the runner."
- name: List files in the repository
run: |
ls ${{ github.workspace }}
- run: echo "🍏 This job's status is ${{ job.status }}."
- Remeber to save all changes
- Commit and push the changes to origin (the github repository created)
In order to check that the action created was successfuly created, open your repository on GitHub and select the actions tab. You should be able to see the action running or completed.
The first two lines define the name of the workflow name: GitHub Actions Demo
, and the title of each run of the workflow run-name: ${{ github.actor }} is testing out GitHub Actions 🚀
.
GitHub provides parameters such as actor, action, etc. You can find the all in the GitHub Actions documentation on contexts.
The next section defines how the workflow is triggered.
on:
push:
branches:
- main
Basically, the action will only be triggered when a push to the main branch is made. This can be on push, pull requests, issues, etc. Find more in events that trigger workflows (GitHub Documentation).
A workflow run is made up of one or more jobs, which run in parallel by default. To run jobs sequentially, you can define dependencies on other jobs indicating that a given job needs
another job.
Inside the workflow, the element jobs
has a series of individual jobs identified by an id
.
Fields:
runs-on
: To define the type of machine to run the job on.needs
: Is an optional field, which indicates that the job needs another job to finish in order to start the current one.steps
: A list of steps that the job will execute. Each step can either run a script or use an action.
jobs:
job-1:
runs-on: ubuntu-latest
steps:
...
job-2:
runs-on: ubuntu-latest
needs: job-1
steps:
...
A job contains a sequence of tasks called steps. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry.
Each step has many fields, but the key ones are:
name
: A name for your step to display on GitHub.uses
: Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a published Docker container image.with
: A map of the input parameters defined by the action. Each input parameter is a key/value pair. Input parameters are set as environment variables.run
: Runs command-line programs.
For example:
jobs:
terraform-init:
steps:
- name: Checkout repository
uses: actions/checkout@v2
- name: Set up Terraform
uses: hashicorp/setup-terraform@v1
with:
terraform_version: 1.0.0
...
We strongly recommend to read Workflow syntax for GitHub Actions, to find more about the basics on name, triggers, jobs and steps