GitHub does a good job of guiding people in the workflow designer when writing workflows. That’s why it is best to just start and write your first workflow and familiarize yourself withthe platform.
Getting ready
Before you can create your first workflow, you first have to create a repository on GitHub. Navigate tohttps://github.com/new, authenticate if you are not authenticated yet, and fill in data as inFigure 1.6:
Figure 1.6 – Creating a new repository
Pick your GitHub user as the owner and give the repo a unique name – for example,ActionsCookBook. Make it a public repo so that all workflows and storage are free. Initialize the repo with a README file – this way, we have already files in the repo and something in the workflow towork with.
How to do it…
GitHub Action workflows areYAML files with a.yml or .yaml extension that are located in the.github/workflows folderin a repository. You could create the file manually, but then the workflow editor would only work after the first commit. Therefore, I recommend creating a new workflow fromthe menu.
- In your new repository, navigate toActions. Since your repository is new and you don’t have any workflows yet, this will redirect you directly to theCreate new workflow page (
actions/new). If your repository contains workflows, you will see the workflows here (as later displayed inFigure 1.16), and you would have to click theNew workflow button to get tothat page.On this page, you will find a lot of template workflows you could use as a starting point. There are starter workflows fordeployments to most clouds,CI for most languages,security scanning of your code,automation in general, and templates to deploy content to GitHub Pages. You can filter the starter workflows by these categories. These workflows give you a good starting point for most ofyour workflows.
In this recipe, we will focus on familiarizing ourselves with the editor, and we will create a workflow from scratch by clickingset up a workflow yourself (seeFigure 1.7):
Figure 1.7 – Creating a new workflow in GitHub
- GitHubwill create a new
main.yml file in.github/workflows on the default branch and display it in the web editor. On the right side of the editor, you have the documentation, and you can search foractions in GitHub Marketplace. In the editor, you can useCtrl +Space (orOption +Space – depending on your keyboard settings) to trigger autocomplete. The editor will capture theTab key and by default use it for a two-space indentation. To navigate to other controls on the page using theTab key, you first have to exit it usingEsc or usingCtrl +Shift +M.Modify the filename toMyFirstWorkflow.yml and familiarize yourself with the editor (seeFigure 1.8):
Figure 1.8 – The workflow editor for GitHub Actions
- In theeditor, clickCtrl +Space (orOption +Space) to see a list of root elements valid in a workflow file (seeFigure 1.9):
Figure 1.9 – The editor shows you all valid options at a certain level in the workflow file
Typically, workflows are started with thename property, which sets the display name of the workflow in the UI. It’s a good practice to add a comment to the top of the file summarizing the intent ofthe workflow.
- Add a comment to the top of the file and set the
name property using autocomplete. Note that the editor has error checking and indicates that you are still missing the required root key,on (seeFigure 1.10):
Figure 1.10 – Error checking in the code editor
- Next, we are going to configure events that should trigger the workflow. Note that a workflow can have multiple triggers. Depending on where you are in the designer, autocomplete will give you different results. If you are on the same line as
on:, you will get a result in the JSON syntax (see theYAML collection types section); that is,on: [push].If you add a comma after the first element and clickControl +Space again, then you can pick additional elements from autocomplete (seeFigure 1.11):
Figure 1.11 – Autocomplete works also inside squared brackets
Each trigger is a map and can contain additional arguments. If you put your cursor on the line belowon: and add a two-space indentation, autocomplete will give you the results in the full YAML syntax. It will also give you properties that you can use to configure each trigger (seeFigure 1.12):
Figure 1.12 – Autocomplete also helps with options for triggers
Note that most arguments – for example, branches or paths – are sequences and need a dash for each entry if you are not using theJSON syntax.
We want our test workflow to run on every push to themain branch. We also want to be able to trigger it manually (see theEvents that trigger workflows section). Your workflow code for triggers should looklike this:
on: push: branches: - main workflow_dispatch:
Wildcards
The* character can be used as a wildcard in paths and** as a recursive wildcard.* is a special character in YAML, so you need to use quotation marks inthat case:
push:
branches:
- 'release/**'
paths:
- 'doc/**'
- Afterconfiguring the triggers for the workflow, the next step is to add another root element: thejobs. Jobs are a map in YAML – meaning on the next line with two-space indentation, autocomplete will not work as the editor expects you to set a name. Name your job
first_job and go to the next line. The name of the job object can only contain alphanumeric values, a dash (-), and an underscore (_). If you want any other characters to be displayed in the workflow, you can use thename property:jobs: first_job: name: My first job
- Every job needs a runner that executes it. Runners are identified by labels. You will learn more about runners inChapter 4,The Workflow Runtime. We want our workflow to be executed on the latest version of the Ubuntu runners provided by GitHub, so we use the
ubuntu-latest label:runs-on: ubuntu-latest
- A job consists of a sequence of steps that are executed one after the other. The most basic step is the
run: command, which will execute acommand-line command:steps: - name: Greet the user run: echo "Hello world" shell: bash
The name is optional and sets the output of the step in the log. The shell is also optional and will default tobash on non-Windows platforms, with a fallback tosh. On Windows, the default is PowerShell Core (pwsh), with a fallback tocmd. But you could configure any shell you want with the{0} placeholder for the input of the step (that is,shell:perl {0}).
To add variable output, we can useexpressions that are written between${{ and}}. In the expression, you can use values from context objects such as the GitHub context. Note that autocomplete also works for these context objects (seeFigure 1.13):
Figure 1.13 – Autocomplete also works for context objects
Pick theactor from the listof values:
- run: echo "Hello world
from ${{ github.actor }}."
You will learn more about expressions and context syntax throughout the book. But you can refer to the documentation for expressions (https://docs.github.com/en/actions/learn-github-actions/expressions) and context (https://docs.github.com/en/actions/learn-github-actions/contexts) atany time.
- YAMLallows you to write multiline scripts without the need to wrestle with quotations and newlines. Just add the pipe operator (
|) afterrun: and write your script in the next line with a four-space indentation. YAML will treat this as one block until the next element – even with new and blank linesin it:- run: | echo "Hello world from ${{ github.actor }}." echo "Current branch is '${{ github.ref }}'."
- GitHub Actions workflows will not automatically download the code from your repository. If you want to do something with files in your repository, you have to check out the content first. This is done using a GitHub action – a reusable workflow step that can easily be shared formultiple workflows.
On the right side of the workflow editor is themarketplace. You can directly search there for all kinds of actions. Search forcheckout and locate the action fromactions (these are built-in actions from GitHub). In the listing, you see the owner of the action, the latest version, and the stars of the repository. The listing contains anInstallation section that you can copy into your workflow to use the action (seeFigure 1.14):
Figure 1.14 – Listing of the marketplace in the workflow editor
Note that many parameters are optional. To check out the repo, you only need thefollowing lines:
- name: Checkout uses: actions/checkout@v4.1.0
Using GitHub Actions
Actions refer to a location on GitHub. The syntax is{path}@{ref}. The path points to a physical location on GitHub and can be{owner}/{repo} if the actions are in the root of a repository or{owner}/{repo}/{path} if the actions are in a subfolder. The reference after@{ref} is anygit reference that points to a commit. It can be atag,branch, or an individualcommitSHA.
- To display the files in our repository after checking them out, we’ll add anextra step:
- run: tree
This will output the files in the repository in atree structure.
- To run the workflow, just commit the workflow file to the
main branch. ClickCommit changes…, leave the commit message and branch, and clickCommit changes in the dialog to finish the operation (seeFigure 1.15):
Figure 1.15 – Committing the workflow file
- As we have set a push trigger for the
main branch, our commit has automatically triggered the workflow. If you navigate now toActions in your repository, you will be able to see your workflow and the latest workflow run (seeFigure 1.16):
Figure 1.16 – The default view in Actions displays the latest workflow runs of all workflows
Note that thename of the workflow run is the commit message. You can also see the commit that triggered the workflow and the actor that pushedthe changes.
- Click on the workflow run to see more details. The workflow summary page contains jobs on the left and a visual representation on the right (seeFigure 1.17). It also contains metadata for the trigger, the status, andthe duration:
Figure 1.17 – The workflow summary page
- Click on the job to view more details. In the workflow log, you can inspect the individual steps. Note that each line of the workflow file has a clickable number – that is a URL that you could use to identify each line. TheSet up job step is a special step that gives you a lot of background information about the workflow runner and workflow permissions (seeFigure 1.18). Inspect the output of all steps ofyour workflow:
Figure 1.18 – The workflow log for an individual job
- As a last step, we want to trigger the workflow manually to also see the difference in the workflow run. Go back toActions, select the workflow on the left side (seeFigure 1.19), and runthe workflow:
Figure 1.19 – Triggering a workflow manually through the UI
Inspect the new workflow run andits output.
How it works…
Workflow filesare YAML files located in the.github/workflows folder ina repository.
YAML basics
YAML stands forYAML Ain’t Markup Language and is a data-serialization language optimized to be directly writable and readable by humans. It is a strict superset of JSON but with syntactically relevant newlines and indentation insteadof braces.
You can write comments by prefixing text with ahash (#).
In YAML, you can assign a value to a variable with the following syntax:key: value.
key is the name of the variable. Depending on the data type ofvalue, the type of the variable will be different. Note that keys and values can contain spaces and do not need quotation marks! Only add them if you use some special characters or you want to force certain values to be a string. You can quote keys and values with single or double quotes. Double quotes use the backslash as the escape pattern ("Foo \"bar \" foo"), while single quotes use an additional single quote for this ('foo ''bar'' foo').
YAML collection types
In YAML, there are two different collection types: nested types called maps and lists – also called sequences. Maps use two spacesof indentation:
parent_type: key1: value1 key2: value2 nested_type: key1: value1
A sequence is an ordered list of items and has a dash beforeeach line:
sequence: - item1 - item2 - item3
Since YAML is a superset of JSON, you can also use the JSON syntax to put collections inone line:
key: [item1, item2, item3]key: {key1: value1, key2: value2}Events that trigger workflows
There are three types of triggers for workflows:webhook triggers,scheduled triggers, andmanual triggers.
Webhook triggers startthe workflow based on an event in GitHub. There are many webhook triggers available. For example, you could run a workflow on anissues event, arepository event, or adiscussions event. Thepush trigger in our example is awebhook trigger.
Scheduled triggers canrun the workflow at multiple scheduled times. The syntax is the same syntax used forcron jobs:
on: schedule: # Runs at every 15th minute - cron: '*/15 * * * *' # Runs every hour from 9am to 5pm - cron: '0 9-17 * * *' # Runs every Friday at midnight - cron: '0 2 * * FRI'
Manual triggers allowyou to start the workflow manually. Theworkflow_dispatch trigger will allow you to start the workflow using the web UI or GitHub CLI. You can define input parameters for this trigger using theinputs property. Therepository_dispatch trigger can be used to trigger the workflow using the API. This trigger can also be filtered by certain event types and can accept additional JSON payload that can be accessed inthe workflow.
To learn more about triggers, check the documentationathttps://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows.
Jobs
Every job needs a runner that executes it. Runners are identified by labels. In our recipe, we use theubuntu-latest label. This means that our job will be executed on the latest Ubuntu image hosted by GitHub. You will learn more about runners inChapter 4, TheWorkflow Runtime.
Using GitHub Actions
Actions refer to alocation on GitHub. The syntax is{path}@{ref}. The path points to a physical location on GitHub and can be{owner}/{repo} if the actions are in the root of a repository or{owner}/{repo}/{path} if the actions are in a subfolder. The reference after@{ref} is anygit reference that points to a commit. It can be a tag, branch, or an individualcommit SHA:
# Reference a version using a tag- uses: actions/checkout@v4.1.0# Reference the current head of a branch- uses: actions/checkout@main# Reference a specific commit- uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab
For local actions in the same repository, you can omit the reference if you check out ofthe repository.
If the action has defined inputs, you can specify them using thewith property:
- uses: ActionsInAction/HelloWorld@v1 with: WhoToGreet: Mona
Inputs can be optional or required. You can also set environment variables for steps using theenv property:
- uses: ActionsInAction/HelloWorld@v1 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}There’s more…
This is just a very basic workflow that uses an action to check out code and runs some commands on the command line. In the next two recipes, I’ll show you how to use secrets, variables, and protected environments for morecomplex workflows.
CANCEL
United States
Great Britain
India
Germany
France
Canada
Russia
Spain
Brazil
Australia
Singapore
Canary Islands
Hungary
Ukraine
Luxembourg
Estonia
Lithuania
South Korea
Turkey
Switzerland
Colombia
Taiwan
Chile
Norway
Ecuador
Indonesia
New Zealand
Cyprus
Denmark
Finland
Poland
Malta
Czechia
Austria
Sweden
Italy
Egypt
Belgium
Portugal
Slovenia
Ireland
Romania
Greece
Argentina
Netherlands
Bulgaria
Latvia
South Africa
Malaysia
Japan
Slovakia
Philippines
Mexico
Thailand
SALE ENDS IN
