GitHub Actions Tutorial: A Complete Guide with Examples
Once you know what GitHub is and how to use GitHub to host websites, you can move further and take full advantage of everything GitHub offers. One of such things is GitHub Actions.
GitHub Actions enables developers to automate workflows across issues, pull requests, and more, all within GitHub. Unlike other automation features, GitHub Actions goes well beyond the usual applications of testing, building, and deploying code. But that’s not all—it also brings continuous integration/continuous deployment to GitHub. The feature brings automation into the software development lifecycle using event-driven triggers, ranging from creating pull requests to building a new brand in a repository.
GitHub Actions offers several benefits, including automating various steps and phases in the software development cycle, such as creating pull requests, adding a new joiner to a repository, merging pull requests, and many more. Additionally, the feature allows users to set organization rules, for example, assigning developer permissions.
In this GitHub Actions tutorial, we will cover how to set up GitHub actions in your repository, how to set up your first GitHub Action, outline best practices to follow, and explore examples of how to use GitHub Actions.
Getting Started With GitHub Actions
Before we explore how to set up GitHub Actions, we need to understand how it works. All GitHub Actions automations are handled using workflows. Every workflow consists of several core concepts: events, jobs, steps, actions, and runners. Let’s explore them in detail.
Workflows
A workflow is an automated process made up of several jobs that are carried out when triggered by events. Workflows are defined in YAML files and stored in a .githubworkflows directory in the repository.
Events
Events are defined triggers that start a workflow, such as creating a branch, opening a pull request, or commenting on an issue.
Jobs
Jobs are tasks that are executed in a workflow when an event is triggered. A workflow can have multiple jobs running in parallel.
Actions
Actions are used to perform complex tasks that you may import into workflows, such as sending a notification email. You can build your own actions or reuse open-source actions available on the GitHub marketplace.
Everhour is the top choice for small businesses and small to mid-size teams of 5 to 50 members, including professionals like software developers, marketers, designers, consultants, lawyers, you name it!
Seamlessly integrating with popular project management tools like Asana, Trello, and Jira, its user-friendly interface and customizable reports make it the ultimate time tracking solution for small and mid-size teams.
With dedicated support ensuring you receive timely assistance, our team is here to help you promptly and with a smile!
Runner
A runner is a series of tasks that are executed in a workflow when triggered by an event. Each runner is responsible for executing a single job.
To summarize, GitHub Actions uses workflows, which are automated processes that are made up of jobs, events, actions and runners. Events are triggers that start a workflow, jobs are tasks executed in a workflow, when an event is triggered, actions are used to perform complex tasks that are imported into workflows, and runners execute a single job. Now that we’ve explored the components of a GitHub Action, let’s go through the set-up process.
Setting Up GitHub Actions
To set up GitHub Actions, you will need to create a GitHub account and a new repository where you want to create workflows. Now, it’s time to create a workflow:
1. Create a .github/workflows directory in an existing repository or create a new one.
2. In the .github/workflows directory, create a file and name it github-actions-demo.yml.
3. Copy the following code into the github-actions-demo.yml file:
| name: GitHub Actions Demo run-name: ${{ github.actor }} is testing out GitHub Actions 🚀 on: [push] 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@v3 – 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 }}.” |
4. Go to the bottom of the page and click ‘Create a new branch for this commit and start a pull request.’ To create a pull request, click ‘Propose new file.’ Committing the workflow file to a specific branch in your repository will trigger the push event and your workflow will start.
GitHub Actions Examples
GitHub Actions is used to automate aspects of the software development lifecycle. There are almost endless GitHub Actions available to users, but here are some useful examples from GitHub documentation and the GitHub marketplace:
1. Read contents of a file
Below is the code for reading the contents of a file:
| steps: – name: Checkout repository uses: actions/checkout@v3 – name: Read package.json id: package uses: juliangruber/read-file-action@v1 with: path: ./package.json – name: Echo package.json run: echo “${{ steps.package.outputs.content }}” |
Learn more about this GitHub Action here.
2. Preventing a failing matrix job for failing a workflow run
This GitHub Action allows specific jobs in a matrix to fail without failing the entire workflow run. Set to true to allow a workflow run to pass, even when a job fails:
| runs-on: ${{ matrix.os }} continue-on-error: ${{ matrix.experimental }} strategy: fail-fast: false matrix: node: [13, 14] os: [macos-latest, ubuntu-latest] experimental: [false] include: – node: 15 os: ubuntu-latest experimental: true |
You can learn more about this GitHub Action here.
3. Return fromJSON for value
This GitHub Action returns a JSON object or JSON data type for value. This function can be used to provide a JSON object as an evaluated expression or to convert environment variables from a string.
For example, the workflow below sets a JSON matrix in one job and then passes it to the next job using an output and fromJSON:
| name: build on: push jobs: job1: runs-on: ubuntu-latest outputs: matrix: ${{ steps.set-matrix.outputs.matrix }} steps: – id: set-matrix run: echo “matrix={\”include\”:[{\”project\”:\”foo\”,\”config\”:\”Debug\”},{\”project\”:\”bar\”,\”config\”:\”Release\”}]}” >> $GITHUB_OUTPUT job2: needs: job1 runs-on: ubuntu-latest strategy: matrix: ${{ fromJSON(needs.job1.outputs.matrix) }} steps: – run: build |
You can learn more about the fromJSON GitHub Action here.
4. Filtering first-time contributors’ pull requests and issues
Here is the code for filtering pull requests and issues from first-time contributors:
| name: ‘First interaction’ description: ‘Greet new contributors when they create their first issue or open their first pull request’ author: ‘GitHub’ inputs: repo-token: description: ‘Token for the repository. Can be passed in using {{ secrets.GITHUB_TOKEN }}’ required: true issue-message: description: ‘Comment to post on an individual”s first issue’ pr-message: description: ‘Comment to post on an individual”s first pull request’ runs: using: ‘docker’ image: ‘Dockerfile’ |
You can find this GitHub Action here.
5. Create releases via the GitHub Release API
Below is the code for creating releases via the GitHub Release API. On every push to a tag matching the pattern v*, create a release:
| on: push: # Sequence of patterns matched against refs/tags tags: – ‘v*’ # Push events to matching v*, i.e. v1.0, v20.15.10 name: Create Release jobs: build: name: Create Release runs-on: ubuntu-latest steps: – name: Checkout code uses: actions/checkout@v2 – name: Create Release id: create_release uses: actions/create-release@v1 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions, you do not need to create your own token with: tag_name: ${{ github.ref }} release_name: Release ${{ github.ref }} body: | Changes in this Release – First Change – Second Change draft: false prerelease: false |
Doing this will create a Release and a release event.
You can find this GitHub Action here.
GitHub Actions Best Practices
When using GitHub Actions in your workflows, there are several best practices you should follow to ensure they run efficiently and securely:
🕵️♀️ Monitor workflows
First and foremost, to ensure workflows are running correctly, make sure to monitor them as they run, and make changes if required.
💁♀️ Keep Actions minimal
Actions’ have high bandwidth but are fast to complete. However, the longer an action takes to set up and then run, the more time you have to wait. For this reason, it’s best to keep Actions minimal.
🔁 Make sure every repository contains a CI/CD workflow
Every repository in your organization should have a GitHub Actions workflow in place if you’re relying on it as a CI/CD pipeline. It’s not too difficult to manually check a handful of repositories. However, doing this across many repositories will increase the chance of human error and give you significantly less visibility into which repositories are properly integrated and which need fixing.
⌛ Set workflow timeouts
GitHub Actions kills workflows by default if they have not finished within six hours. While most workflows do not need that much time to complete, sometimes errors mean the job is killed after six hours have elapsed. It’s best to set a shorter timeout, somewhere around 30 minutes should be enough time.
🔐 Use Secrets to store sensitive information
Tokens or passwords should be stored using GitHub Secrets to ensure they stay secure. Secrets are encrypted variables created in an organization, repository, or repository environment to ensure sensitive information stays encrypted until it is used in a workflow.
😎 Use descriptive names
To ensure you understand your workflows fully, use descriptive names for jobs and steps to make the process easier to understand and modify if needed, as this will help you reduce the number of errors.
🤝 Use the GitHub Actions marketplace
Use the GitHub Actions marketplace to discover hundreds of Actions created and published by other developers. You’ll find a wide selection of pre-built Actions that will save you time and effort when it comes to building efficient workflows.
GitHub Actions Tutorial: In Summary
GitHub Actions is a powerful tool that allows developers to automate workflows across pull requests, issues, and much more. The tool brings CI/CD to GitHub, making automation a key part of the software development lifecycle.
In this article, we explored how to set up GitHub Actions in your chosen repository, how to set up your first ever GitHub Action in a workflow, some examples of commonly used GitHub Actions, and several best practices for you to follow to reduce the likelihood that you’ll run into problems. We hope this GitHub Actions Tutorial helps you make the most of the tool, as it makes software development faster and more reliable.
To learn more about GitHub Actions, we recommend reading through the GitHub Actions Docs page. There, you’ll find more information about how to use GitHub Actions to accelerate development workflows, continuous integration, deploying with GitHub Actions, and example workflows that demonstrate the CI/CD features of the tool.
Integrate GitHub with Everhour
If you’d benefit from tracking the time you spend on GitHub, consider integrating the platform with Everhour. The platform has many valuable features suitable for organizations of all kinds, including GitHub time tracking, billing and budgeting, task management, team management, expenses tracking and reporting tools.
The time tracker is perfect for organizations looking to implement employee time tracking to boost efficiency and productivity. For example, platform has a handy time clock app that takes all of the hard work out of team management. But that’s not all—Everhour also provides a timesheet app, an attendance tracker and a work hours tracker, so you can keep an eye on team progress.
