GitHub Actions Workflow Syntax: Defaults with Examples

Understanding GitHub Actions Workflow Syntax: Defaults with Examples

Introduction

GitHub Actions provide powerful tools for automating, customizing, and executing software development workflows within repositories. One critical aspect of defining these workflows is understanding the syntax, especially the use of defaults. In this post, we’ll dive deep into the defaults field in GitHub Actions workflow syntax and discuss its usage with illustrative examples.

Overview of GitHub Actions Workflow Syntax

Workflows are custom automated processes that developers can set up in their repositories to build, test, package, or deploy their code. GitHub Actions workflows are defined in YAML files located in the .github/workflows directory of the repository. These files specify what events trigger the workflow, what jobs are to be run, and the steps that comprise each job.

Understanding the defaults Field

The defaults field is a top-level key in a workflow file, offering a way to set default settings for all jobs and steps within a workflow. It can be particularly handy when you want to apply a certain configuration, like a specific shell or working directory, to all jobs and steps in a workflow.

Here’s an example of a workflow file with a defaults field:

In the example above, the defaults field is used to set a default shell (bash) and working directory (/usr/src/app) for all run steps in the workflow. This means, for example, that the ./script.sh command in the Run a script step will be executed in the /usr/src/app directory using bash.

Let’s break down the components of the defaults field:

  • run: This key allows you to set defaults for all run steps in the workflow.
  • shell: The shell in which the commands are run. This can be any shell that your runner’s operating system supports.
  • working-directory: The directory in which the commands are run. If this directory does not exist, it will be created for the duration of the step and removed at the end.

Applying defaults to Jobs

In addition to setting defaults for the entire workflow, you can also set defaults for individual jobs. This can be useful when different jobs in the workflow need different default configurations. Defaults set at the job level override defaults set at the workflow level.

Here’s an example:

In the example above, the build job has its own defaults field, setting a default shell (pwsh) and working directory (/usr/src/build). This means the ./script.ps1 command in the Run a script step will be executed in the /usr/src/build directory using pwsh, even though the workflow-level defaults specified bash as the shell and /usr/src/app as the working directory.

Conclusion

Understanding and utilizing the defaults field in GitHub Actions workflow syntax can simplify your workflows and make them more readable and maintainable. By setting default configurations at the workflow or job level, you can ensure consistency across steps and jobs, and override these defaults where necessary.

GitHub Actions offer immense flexibility for automating your software development workflows. While this post focused on the defaults field, remember that there are many other aspects of GitHub Actions workflow syntax worth exploring.