gh-actions Lecture Notes

‏ ‏ ‎ ‏ ‏ ‎

1. Prerequisites - What students have to prepare

2. Learning Resources

3. Introduction

→ Microsoft-tutorial

3.1. Actions

Actions are the mechanism used to provide workflow automation within the GitHub environment.

They’re often used to build continuous integration (CI) and continuous deployment (CD) solutions.

However, they can be used for a wide variety of tasks:

Automated testing.
Automatically responding to new issues, mentions.
Triggering code reviews.
Handling pull requests.
Branch management.

They’re defined in YAML and stay within GitHub repositories.

Actions are executed on "runners," either hosted by GitHub or self-hosted.

Contributed actions can be found in the GitHub Marketplace. See Marketplace Actions

3.2. Workflows

Figure 1. actions flow

GitHub tracks events that occur. Events can trigger the start of workflows.
Workflows can also start on cron-based schedules and can be triggered by events outside of GitHub.
They can be manually triggered.
Workflows are the unit of automation. They contain Jobs.
Jobs use Actions to get work done.
Workflows define the automation required. It details the events that should trigger the workflow.
Also, define the jobs that should run when the workflow is triggered.
The job defines the location in which the actions will run, like which runner to use.
Workflows are written in YAML and live within a GitHub repository at the place .github/workflows.
GitHub Actions Tutorial: A Complete Guide with Examples (nice examples for issues and releases)

Unresolved directive in index.adoc - include::../../.github/workflows/demo-workflow-file.yaml[]

run the first workflow

Figure 2. When a indentation error occurs

You can find a set of starter workflows here: Starter Workflows.

You can see the allowable syntax for workflows here: Workflow syntax for GitHub Actions

3.3. Standard workflow syntax elements

Workflows include several standard syntax elements.

Name: is the name of the workflow. It’s optional but is highly recommended. It appears in several places within the GitHub UI.
On: is the event or list of events that will trigger the workflow.
Jobs: is the list of jobs to be executed. Workflows can contain one or more jobs.
Runs-on: tells Actions which runner to use.
Steps: It’s the list of steps for the job. Steps within a job execute on the same runner.
Uses: tells Actions, which predefined action needs to be retrieved. For example, you might have an action that installs node.js.
Run: tells the job to execute a command on the runner. For example, you might execute an NPM command.

You can see the allowable syntax for workflows here: Workflow syntax for GitHub Actions.

3.4. Events

Events are implemented by the on clause in a workflow definition.

There are several types of events that can trigger workflows.

3.4.1. Scheduled events

With this type of trigger, a cron schedule needs to be provided.

on:
    schedule:
        - cron: '0 8-17 * * 1-5'

Cron schedules are based on five values:

Minute (0 - 59)
Hour (0 - 23)
Day of the month (1 - 31)
Month (1 - 12)
Day of the week (0 - 6)

Aliases for the months are JAN-DEC and for days of the week are SUN-SAT.

A wild card means any. (* is a special value in YAML, so the cron string will need to be quoted)

So, in the example above, the schedule would be 8 AM - 5 PM Monday to Friday.

3.4.2. Code events

Code events will trigger most actions. It occurs when an event of interest occurs in the repository.

on:
    pull_request

The above event would fire when a pull request occurs.

on:
    [push, pull_request]

The above event would fire when either a push or a pull request occurs.

on:
    pull_request:
        branches:
           - develop

The event shows how to be specific about the section of the code that is relevant.

In this case, it will fire when a pull request is made in the develop branch.

3.4.3. Manual events

There’s a unique event that is used to trigger workflow runs manually. You should use the workflow_dispatch event.

Your workflow must be in the default branch for the repository. Webhook events

Workflows can be executed when a GitHub webhook is called.

on:
    gollum

This event would fire when someone updates (or first creates) a Wiki page.

3.4.4. External events

Events can be on repository_dispatch. That allows events to fire from external systems.

For more information on events, see Events that trigger workflows.

3.5. Jobs

Workflows contain one or more jobs. A job is a set of steps that will be run in order on a runner.

Steps within a job execute on the same runner and share the same filesystem.

The logs produced by jobs are searchable, and artifacts produced can be saved.

3.5.1. Jobs with dependencies

By default, if a workflow contains multiple jobs, they run in parallel.

jobs:
  startup:
    runs-on: ubuntu-latest
    steps:
      - run: ./setup_server_configuration.sh
  build:
    steps:
    - run: ./build_new_server.sh

Sometimes you might need one job to wait for another job to complete.

You can do that by defining dependencies between the jobs.

jobs:
  startup:
    runs-on: ubuntu-latest
    steps:
      - run: ./setup_server_configuration.sh
  build:
    needs: startup
    steps:
      - run: ./build_new_server.sh

If the startup job in the example above fails, the build job won’t execute.

For more information on job dependencies, see the section Creating Dependent Jobs at Managing complex workflows.

3.6. Runners

When you execute jobs, the steps execute on a Runner.

The steps can be the execution of a shell script or the execution of a predefined Action.

GitHub provides several hosted runners to avoid you needing to spin up your infrastructure to run actions.

Now, the maximum duration of a job is 6 hours, and for a workflow is 72 hours.

For JavaScript code, you have implementations of node.js on:

Windows
macOS
Linux

If you need to use other languages, a Docker container can be used. Now, the Docker container support is only Linux-based.

These options allow you to write in whatever language you prefer.

JavaScript actions will be faster (no container needs to be used) and more versatile runtime.

The GitHub UI is also better for working with JavaScript actions.

3.6.1. Self-hosted runners

If you need different configurations to the ones provided, you can create a self-hosted runner.

GitHub has published the source code for self-hosted runners as open-source, and you can find it here: https://github.com/actions/runner.

It allows you to customize the runner completely. However, you then need to maintain (patch, upgrade) the runner system.

Self-hosted runners can be added at different levels within an enterprise:

Repository-level (single repository).
Organizational-level (multiple repositories in an organization).
Enterprise-level (multiple organizations across an enterprise).

GitHub strongly recommends that you don’t use self-hosted runners in public repos.

Doing it would be a significant security risk, as you would allow someone (potentially) to run code on your runner within your network.

For more information on self-hosted runners, see: About self-hosted runners.