Demystifying GitHub Actions: A Step-by-Step Guide

Photo by Roman Synkevych on Unsplash

This article dives into the core structure of a GitHub Actions workflow, guiding you through defining the events that trigger the workflow, the individual jobs within the workflow that handle specific tasks, and the breakdown of steps within each job. You’ll learn how to configure the runner environment for each job. Finally, the article explores scheduling workflows using POSIX cron syntax and explains how to define specific UTC times for automated execution.

A basic GitHub Actions workflow will have the following components:

• Workflow Name: A descriptive name for the workflow.
• on: This outlines the events that activate the workflow, such as push, pull_request, and schedule. The push event triggers the workflow in response to code modifications. On the other hand, the schedule event initiates the workflow according to a predetermined timetable, irrespective of code alterations. For the push event, you can specify the branches that activate the workflow. By default, the schedule event operates on the default branch, and there's no option to specify other branches in the schedule configuration.
• jobs: This section contains one or more jobs that define the tasks to be executed. In the context of Playwright automation, two jobs are primarily involved. The first job installs all dependencies, including Playwright, and then runs the tests. The second job generates an HTML report. If sharding is used during test execution, an additional step is required to merge the individual shards before generating the HTML report.
• Job Name: Each job should have a name.
• runs-on: Specifies the type of runner environment for the job.
• steps: Contains the sequence of steps to be executed within the job.
• Step Name: A name for the step.
• uses/run: This instruction guides the workflow to utilize a particular action. Actions are reusable code units executed within a GitHub Actions workflow. There are predefined actions, such as checking out the repository’s code onto the runner machine, setting up the Node.js environment on the runner, or uploading artifacts to GitHub Actions, among others. A version tag at the end of an action specifies which version of the action to use.
• if: Sets conditions for the execution of conditional steps. If the condition evaluates to false, the step will be skipped, and the workflow will continue to the next step.
• continue-on-error: Specifies whether to continue running subsequent steps if this step fails.

The path .github/workflows is where your GitHub Actions files are stored. This directory is crucial for organizing and executing GitHub Actions, enabling seamless integration and operation. The file's actual name within this location does not affect how GitHub interprets its contents; it’s the file's content, not the name, that matters.

mkdir -p .github/workflows
touch .github/workflows/playwright.yml

The mkdir command creates the .github/workflows directory structure. The -p option guarantees the creation of parent directories (.github and workflows) if they are not already present. The touch the command creates an empty yml file named playwright.

We’ll start by creating a simple workflow with two jobs. The first job installs all dependencies, including Playwright, and then runs the tests. The second job generates an HTML report.

npm ci

npm is a package manager for Node.js, managing dependencies and scripts. ci stands for “continuous integration.” is a command in npm used in continuous integration environments.

npx playwright install --with-deps chromium

This is a combination command to install Playwright, the Chromium browser, and its dependencies in one go. npx is a package runner tool that comes with npm. It runs packages from the npm registry, and if a package isn’t installed locally, npx will automatically download and execute it. By default, Playwright installs all supported browsers (Chromium, Firefox, and WebKit). However, specifying them explicitly can help minimize dependencies and conserve installation time.

name: Simple workflow

on:
  push:
    branches:
      - main

jobs:
  test_execution_job:
    name: Test Execution
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright Browsers
        run: npx playwright install --with-deps chromium

      - name: Run Playwright tests
        run: npm run test

      - name: Upload blob report to GitHub Actions Artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-report-${{ github.run_id }}
          path: blob-report
          retention-days: 30

This job operates on the latest Ubuntu virtual machine provided by GitHub Actions. The workflow begins by checking out the repository’s code to the runner machine. After setting up the Node.js environment with version 20, the npm ci command installs project dependencies based on the package-lock.json file. Subsequently, Playwright and its dependencies, including Chromium, are installed.

The npm run test The command executes the Playwright tests defined in the project. After the test execution, the generated blob report is uploaded as an artifact to GitHub Actions. This artifact can be accessed later for review or analysis.

You can use POSIX cron syntax to schedule a workflow to run at specific Coordinated Universal Time (UTC) times. These scheduled workflows operate on the latest commit on the default or base branch. The minimum interval between scheduled workflows is five minutes.

For straightforward scheduling, visit https://www.utctime.net/utc-time-zone-converter to convert time zones. Below, we discuss the conventions used in cron to generate and understand cron expressions. Entering your desired schedule on https://crontab.guru/ will translate it into the corresponding POSIX cron syntax.

cron ‘0 11 * * 1–5’

• 0 in the first field represents the minute (0 minutes past the hour).
• 11 in the second field represents the hour (11 AM).
• * in the third field represents any day of the month.
• * in the fourth field represents any month.
• 1-5 in the fifth field represents Monday to Friday.

this cron expression schedules a job to run at 11:00 AM from Monday to Friday.

My recent publication compiled a comprehensive collection of 100 similar typescript programs. Each program not only elucidates essential Typescript concepts and expounds upon the significance of test automation but also provides practical guidance on its implementation using Playwright. This resource will undoubtedly be valuable if you look deeper into similar topics.

Playwright's Cookbook: Recipes with Typescript