GitHub Actions in practice

Back in 2018, GitHub introduced a new feature called GitHub Actions. At the very beginning, it served as a useful tool for orchestrating workflows. Based on events, one could perform various effects on GitHub. Over time, the project grew and started to provide more and more possibilities; for example, continuous integration and continuous delivery (CI/CD).

One of the vast advantages GitHub Actions provides is configuring the action to any event occurring on a workflow repository, including opening a pull request, pushing a commit, and many others. We can also configure events that occur outside of GitHub and trigger a repository_dispatch event on GitHub in response. It's also possible to schedule run time, or even start a workflow manually. In general, the effect can be any task that can be executed on an assigned runner - such as deploying a project or running tests.

Advantages of using GitHub Actions

There are many benefits to using GitHub Actions in your workflows as it opens many doors for project optimization. Below, we listed the perks we enjoy the most.

🌐 Cross-platform processing

Runners are the machines that execute jobs in a GitHub Actions workflow. By default, they're hosted on virtual machines with a variety of choices in their operating systems. You can run your workflows on Linux, macOS, Windows, or even choose your own self-hosted runner. Since it's all very customizable, you can adjust the setup to your needs. Each runner offers a different size of RAM or disk space.

🕐 Time-saving matrix builds

With GitHub Actions, you can process your workflows in parallel. It's a great solution for testing, as each entity can be run independently, which can save you a lot of time.

🗣️ Variety of available programming languages

GitHub Actions is very user-friendly and supports many programming languages and environments. The supported languages include the popular ones like Node.js, Java, and Python, but there are various other options.

⏺️ Live logs

GitHub lets you to easily follow a run of your workflow in real-time. It's extremely handy for debugging and spotting any mistakes in your code. There's also a convenient option to send your logs to other members of your team. Moreover, the logs support colors and emojis! 🎉😄

Note that the above is only a brief summary. If the topic captures your interests, be sure to check out everything GitHub Action has to offer in their documentation.

Usage

At their core, GitHub Actions are made up of one or more individual tasks. Developers can use the pre-built actions and scripts provided by GitHub, or they can create workflows with their own custom actions and scripts to suit their specific needs.

A new workflow file has to be defined by YAML syntax and placed in the .github/workflows directory of your project. In this workflow file, we need to specify:

• The name of the workflow based under the key name.
• The action trigger with the key on.
• The jobs that define the effects we want to perform on the repository. Each job is divided into steps.

And that's initially all you'll need to configure in your workflow file to run your first workflow!

Example of a workflow file

For the first time in LiveChat projects, we used GitHub Actions to solve the problem of broken links in our documentation. Due to the size of the API docs, it was very difficult to manually ensure each redirect was valid and working.

As we mentioned before, in the workflow file, GitHub Actions lets us specify the scheduled time as a workflow trigger. This proved to be very handy in our case. In addition, we used two external actions: lychee-action to check the links in the Markdown files, and create-issue-from-file to create a GitHub Issue based on the output of the first action.

Take a look at the full workflow file example below.

name: Links

on:
  repository_dispatch:
  workflow_dispatch:
  schedule:
    - cron: '00 11 * * 1'

jobs:
  linkChecker:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Link Checker
        uses: lycheeverse/lychee-action@v1.0.8
        with:
          args: --verbose --no-progress **/*.mdx **/*.md **/*.html
        env:
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

      - name: Create Issue From File
        uses: peter-evans/create-issue-from-file@v3
        with:
          title: Link Checker Report
          content-filepath: ./lychee/out.md
          labels: report, automated issue

As you can see, it's a pretty simple one, yet allowed us to switch from a tedious manual workflow done by hand to an automatic and scheduled workflow we simply need to verify the contents of.

Can you manually trigger a GitHub Actions workflow?

Yes! If you'd like to test your GitHub Actions with a manual trigger, you can do it in a few simple steps.

💡 Before you begin, note that to be able to manually trigger your workflow, you have to configure it to run on a workflow dispatch trigger and have your workflow on the default branch. Read more in GitHub docs.

1. First, navigate to the repository where your GitHub Action is defined. There, you should click on the Actions tab at the top of the repository page.
2. Once in the Actions tab, you should find the workflow that you want to manually trigger, and click on it to open the details page.
3. Next, you should see a Run workflow button towards the top right of the screen. Click on this button to manually trigger the action.
4. You'll be prompted to select the branch to use for the manual run. If the action is set up to run on multiple branches, you can select the desired branch here. If the action is only set up to run on a single branch, this step should be skipped.
5. Once you've selected the branch, click on the green Run workflow button to start the manual run.
6. That's it! Your GitHub Action should now be running a workflow manually, and you can monitor its progress using the same interface that you use to monitor its regular automatic runs.

It's worth noting that some GitHub Actions may not be designed for a manual trigger, or may require additional setup or configuration before they can be manually run. However, for most actions, the steps from above should be all you need to manually trigger the action and start running it right away!

Summary

GitHub Actions is a very useful and user-friendly way to automate your repository workflows. Also, the available configuration options are a huge benefit when it comes to customizing GitHub Actions workflows to your company's environment and expectations.

It opens many doors for various use cases, so we highly recommend checking it out. I'm sure we'll use them for other purposes in our repositories at LiveChat.

💡 Read more about GitHub Actions in their documentation >>