Peter MbanugoGitHub is fast becoming an all-in-one platform where developers build, maintain and ship their software. You may use it primarily as a collaborative code management tool for your software. But today, you have features like:
- Codespaces, a cloud-powered development environment that allows you to build, run and debug your code in the cloud.
- Actions, an automation platform that allows you to automate your development workflow.
I'm going to focus on GitHub Actions in this post. This will be a basic introduction to the concept of GitHub Actions for developers of all skill levels. I'll start out with a simple action that prints out text, and then finish off with an Actions workflow that will run the test script of a Node.js application.
What Is GitHub Actions?
GitHub Actions is an event-driven, automation platform that allows you to run a series of commands after a specified event has occurred. For example, when a commit is made to your staging branch, and you want to build, test and then deploy the changes to your staging environment. With Actions, you can automate tasks within your development lifecycle, all within GitHub.
A common use case for Actions is automated continuous integration and deployment, and you may ask if you need to know yet another CI/CD tool, or which is better. GitHub Actions is much more than a CI/CD tool. You can use it to automate any task based on any event related to your GitHub project. They can be events related to GitHub Issues where you want to automatically triage issues and label them, or block pull requests that reference no existing issues. It's more of an automation tool than a CI/CD tool.
Your First Hello World GitHub Actions
We're going to create a simple Actions workflow that can be manually invoked, or run automatically for every commit pushed to the main branch. GitHub Actions are stored in your repository, in a directory called .github/workflows, and they're defined using the YAML syntax.
To get started, fork and clone this repository on GitHub. Create the directory .github/workflows, then add a new file hello-world-actions.yml and paste the code below in it.
# This is a basic workflow to help you get started with Actions
#The name of your workflow that'll be displayed in the Actions tab
name: Hello-World-Actions
# Events that control when the action will run.
on:
# Triggers the workflow on push events but only for the main branch
push:
branches: [main]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
# This workflow contains a single job called "say_hello"
say_hello:
# The type of runner that the job will run on
runs-on: ubuntu-latest
# Steps represent a sequence of tasks that will be executed as part of the job
steps:
# Runs a single command using the runners shell
- name: Say Hello
run: echo Hello World!
# Runs a set of commands using the runners shell
- name: Say Goodbye
run: |
echo Job Finished.
echo Goodbye!
Let's break down the content of this file to help you understand the component of GitHub Actions. But before that, commit and push this change to the upstream branch.
Workflow
The file you added represents a workflow. A workflow is a configurable automated process made up of one or more jobs and can be scheduled or triggered by an event. A workflow can be used to build, test, package, release or deploy a project.
GitHub displays the name of your workflow on your repository's Actions page. You can set the name using the name key in your YAML file, and, if omitted, GitHub sets it to the file path relative to the root of the repository. In the example above, we specified the name as Hello-World-Actions.
Events
A workflow can be triggered manually or in response to specific events. To specify the events that trigger a workflow, you use the on keyword.
on:
push:
branches: [main]
workflow_dispatch:
This example executes the workflow on push to the main branch and can be triggered manually from the Actions page because we specified workflow_dispatch.
Jobs, Runners and Steps
A workflow execution is made up of one or more jobs. In our example, we have a single job named say_hello. A job is a set of steps that execute a series of commands, using the specified runner.
A runner is a server that has the GitHub Actions runner application installed. It listens for available jobs, runs one job at a time, and reports the progress, logs and results back to GitHub. You can host your own runner or use GitHub hosted runners. In our example, we're using the Ubuntu runner.
runs-on: ubuntu-latest
After you specify the runner, then you specify the steps with the commands to run.
steps:
# Runs a single command using the runners shell
- name: Say Hello
run: echo Hello World!
# Runs a set of commands using the runners shell
- name: Say Goodbye
run: |
echo Job Finished.
echo Goodbye!
The run keyword tells the job to execute a command on the runner. In this case, run the echo command with the specified values.
Viewing the Workflow Activity
With the changes you made, whenever you push a change to the main branch, it'll run this workflow. Since you already pushed the change to GitHub, you should have had your workflow executed. You will see the workflow executions on the Actions page on GitHub. You can see a visual graph of the progress for each execution, and also drill down into the details of each step.
Follow the instructions below to see the workflow executions:
- Open GitHub and go to the main page of your repository.
- You will find the Actions tab after Pull requests. Click Actions to open the Actions page.
- You should see the workflow listed in the left sidebar, and the run for the workflow listed on the main page. Click any of the workflow runs you would like to see more information about its execution.
Create a Workflow to Run Tests
While you can write your own workflow and actions from scratch, there are community contributed ones that you can use and customize. The GitHub marketplace is a central location for you to find actions created by the GitHub community. We will create a new workflow that will run the test in the project. For this, we will use the GitHub interface to create a workflow using one of the suggested templates, then, within the workflow, you will use a public action to set up Node.js.
Open GitHub and click the Actions tab in order to open the actions page. On the left sidebar, click the New workflow button. You will be presented with a page that contains suggestions for templates that you can modify to create a workflow. Click the Set up this workflow button in the Node.js workflow template card.
This opens the workflow editor with the file prefilled with jobs and steps. Change the name of the file to test.yml. This file is similar to the one you saw earlier but with a few new syntaxes. On lines 17 and 18, you notice the strategy and matrix keywords.
strategy:
matrix:
node-version: [10.x, 12.x, 14.x, 15.x]
The strategy creates a build matrix for the jobs, such that your job will run against the specified variations. In this example, the specified job will run multiple times for the specified Node.js versions in the array. We don't want to run against Node.js 10.x; therefore, we will update line 19 as follows:
node-version: [12.x, 14.x, 15.x, 16.x]
You will notice the use of the uses keyword in this workflow. This is a way to specify actions that you want to execute for the step. An action is a reusable set of commands that can be defined in the same repository as the workflow, a public repository or a Docker image. You can create your own actions, or use actions created by the GitHub community.
The uses: actions/checkout@v2 statement tells the job to retrieve v2 of the community action named actions/checkout@v2. This is an action that checks out your repository at a particular version, then downloads it to the runner. This allows you to run actions against your code, and you can use this action any time your workflow will run against the repository's code.
The actions/setup-node@v2 action installs the Node software package on the runner, thereby giving you access to node and npm commands.
The rest of the command runs npm to install the project dependencies and then run the test script.
Commit and push these changes and observe the workflow run on the Actions page.
Wrap-up
GitHub Actions is a nice addition to the suite of features available on GitHub. It enables you to automate your development tasks and visualize how those tasks run, all within GitHub. It can be used to automate CI/CD tasks or automate how you triage issues or labelling of pull requests. Actions serves as your serverless workflow engine, with the automation code maintained alongside the code for the application. The GitHub marketplace is where you can find actions for common tasks such as building and publishing a Docker image, and you can also create and share your actions in the marketplace.
Try it out, and let me know how Actions worked out for you by leaving a comment here or DMing me on Twitter.
Originally published at https://www.telerik.com/blogs/introduction-github-actions
