Learning GitHub Actions

Chapter 1. The Basics

Welcome to Learning GitHub Actions. I’m excited that you’re here and for all that you’re about to learn. This is an amazing time to be working in the software field. From containers to clusters to clouds, from automation to generative AI, from security to SREs, the opportunities to create and contribute to interesting software projects has never been greater. And thanks to powerful platforms such as GitHub, that creation and contribution has never been easier to do.

GitHub has led the field in developing an ecosystem for managing the components of software and enabling collaboration, as witnessed by the vast number of open-source projects managed in its repositories. And it has continually provided additional value for users through enhancements to its interfaces, tracking contributions and issues, mechanisms to publish and share information, and much more.

For the last decade or slightly longer, creating software effectively has not just been about writing the code. It has been (and is) also about better and faster delivery technologies. The capabilities of continuous integration/continuous delivery (aka CI/CD), DevOps, and related practices are now largely taken for granted and easy to achieve. But historically with GitHub, you still needed to do some amount of integration with a separate tool to provide a delivery pipeline or other significant automation. While there have long been ways to bolt on extended CI/CD processes, GitHub has been missing a truly integrated solution to enable CI/CD and an end-to-end software development lifecycle (SDLC) within its ecosystem. The answer to that has now arrived in the form of GitHub Actions.

So how does GitHub Actions achieve this? How does it provide real value on its own and over other solutions? And, probably most important to you, how do you easily learn it and start to use it for your own needs?

When you’re learning a new technology, it’s important (or at least helpful) to have some basic context before diving into the technical details. So in this chapter, I’ll briefly cover some basic information around the following questions:

• What are GitHub Actions?
• What are the use cases for GitHub Actions?
• What are the costs involved?
• When does moving to GitHub Actions make sense?

By the end of this chapter, you’ll have a solid context to frame the rest of your learning on GitHub Actions. Now, let’s get started.

Prereqs

This book assumes you already have a basic knowledge of Git and GitHub. If that’s not the case, there are a number of free resources to help you understand both.

If you already have a cursory knowledge of GitHub Actions, you can skip to Chapter 2 to start diving in on more technical details. But if you’re new to the technology or need to be able to make an informed decision about whether it makes sense for your project or team, I recommend reading the material here.

What Is GitHub Actions?

You can define GitHub Actions this way: GitHub Actions is an end-to-end GitHub-centric SDLC process. It provides an automation platform and framework that has been missing from GitHub previously and has had to be added on with other solutions such as Jenkins or Travis CI.

There’s a lot packed into that one statement. But let’s key in on two parts that are at the heart of the functionality: automation platform and framework.

Automation Platform

For purposes of the end user, GitHub Actions is a way to create and execute automated workflows tied to GitHub events. Most commonly, you might think of this in the context of CI/CD. As an example, you make a change via a pull request, and GitHub kicks off a continuous delivery pipeline. Prior to GitHub Actions, you would have needed some external tool or process to respond to a notification from GitHub that the pull request happened and then to process it. And the automation that happened after the pull request and initial notification would have been implemented via that external tool.

With Actions, you now have the means to create this automation within a context managed by, and within, GitHub. You can define the what, when, and how for automated responses to events such as pushes or pull requests. For example, when a push happens in a branch of your repository, automatically grab the latest code and attempt to build it. If a pull request happens for a different branch, automatically build and test the code. If that results in a failure, update a GitHub issue. If there’s not a failure, automatically proceed with putting out a new release.

Conveniently, you can create and store your automation definitions and workflows alongside your code in the GitHub repository. And you can edit them there as well. In short, actions make it easier to automate within GitHub because they are a part of GitHub. They are based in a GitHub-provided framework that adds structure and flow. I’ll discuss that next.

Framework

Taking an automation platform from a jumbled collection of mechanisms to an organized and consumable process requires imposing structure and flow. Without them, you simply have a collection of tools. With them, you can assemble truly useful automation to accomplish whatever set of tasks needs to be done.

For Actions, this framework is composed of a core set of related components in GitHub. These components can be put together to execute simple or complex automation in an understandable and predictable way. And this automation is stored in the repository as code.

I’ll be talking more about these individual components in Chapter 2. But for a quick overview, it works like this: In response to an occurrence of a matching event, a workflow definition stored within the repository is triggered, which in turn fires off jobs on designated systems called runners. The jobs are made up of sequences of steps that either invoke a predefined action or run a command on the runner’s OS shell.

While similar capabilities were available previously in GitHub via mechanisms such as API calls, they were not as easy to assemble at a higher level. Developers often had to invest considerable time and effort to learn how to string together the right API calls and/or integrations with other external tooling (such as Jenkins, Travis CI, etc.). Or they would use custom scripting and programming to be able to get to the desired end goal. This was especially true if they wanted to be able to manage processes through GitHub. (Another workaround was to mirror the repository outside of GitHub for products to use.)

Actions implements a native framework in GitHub providing a more seamless and flexible experience. This flexibility is enhanced by the Actions Marketplace, a public registry where actions can be published and shared. If you want to create workflows to do common activities (such as checking out code or building with a particular build tool), you can choose from existing actions in the marketplace. If you want or need more extensive logic, for which an action doesn’t already exist, you can code your own custom action using a well-defined structure. Then you can publish and share it with others via the Marketplace if desired. This approach provides a measure of flexibility, reusability, and extensibility not previously available with GitHub. A secondary benefit is that it can enable rapid prototyping and implementation through combining actions for various use cases. I’ll talk about those topics in the next section.

Actions versus actions

You may notice that at times the term actions is capitalized and other times it is not. This is because there is both the larger framework/platform to talk about and also the smaller, predefined pieces of functionality. Both of these are referred to with the same term. Following a recommendation from GitHub, I’ll refer to the larger platform/framework as GitHub Actions or Actions (uppercase “A”) and the individual units of functionality as actions (lowercase “a”).

What Are the Use Cases for GitHub Actions?

When CI/CD first came on the scene, dedicated tools such as Jenkins were the primary means of creating pipelines. These tools were flexible—arguably, too flexible. You had to work hard to tie together individual parts into a pipeline. Gradually, with the widespread adoption of CI/CD, the concept of pipelines has come into its own as a predefined structure. And so too has the ability to define pipelines that go beyond just the basics of building simple tests. Today’s CI/CD pipelines can be very complex and can include advanced testing, multiple integration levels, and automated deployments/releases. GitHub Actions allows you to create workflows as complex as needed to handle these types of operations without ever leaving GitHub’s ecosystem. Further, it allows you to create as many different workflows as needed for additional automation use cases.

While GitHub Actions does not use the term pipeline in its processes, the overall workflow approach it uses is a similar concept. Workflows chain together smaller units of work called jobs. Jobs are what you often might see in other applications as stages, meaning parts of a larger process that perform a distinct and separate function. In fact, if you’re coming from working with another automation tool, you can think of the overall GitHub Actions flow as being a pipeline, meaning some change or event causes a series of automated actions to happen automatically in response.

The main use cases would be in response to something happening in GitHub. But there are also ways for workflows to be kicked off by events outside of that environment, started on a particular schedule, or even initiated manually through the Actions interface in GitHub. I’ll have more to say about these different ways of initiating a workflow in Chapter 2 and also in Chapter 8.

While CI or CI/CD is the primary purpose that comes to mind, workflows and actions can be used to automate nearly any process. There are two primary places you can look to get ideas about what actions can be used for: the starter workflows and the Actions Marketplace.

Workflows versus actions

Just to make sure it’s clear, workflows are the scripts or pipelines that control the flow and sequence of activity in GitHub Actions. The individual actions are the functions that can be called to do targeted tasks from within workflows (like checking out code).

Starter Workflows

To help users bootstrap using Actions, when you start to create a new workflow, GitHub will present example starter workflows. Figure 1-1 shows an example. You don’t have to use one of these, but if they suit your purpose or come close to it, you can click the Configure button and be working on a new workflow very quickly.

As of the time of this writing, the main categories that have starter workflows are:

Deployment

A set of example workflows for creating deployable objects (like containers) and then deploying them to various cloud platforms

Security

Primarily a set of code-scanning workflows using various security platforms and their tools

Continuous Integration

A large number of workflows that cover the areas of building, testing, and/or publishing for a large number of different programming languages and tools

Automation

Some simple examples for basic automation, including a hello world type, one that demonstrates how to trigger a workflow manually, and a couple that deal with other GitHub constructs such as pull requests and issues

Pages

Workflows to package/deploy sites using common tools like Gatsby, Astro, Jekyll, etc.

You can drill into the full list and code for the starter workflows at https://github.com/actions/starter-workflows.

Figure 1-1. Starter workflows for use with GitHub Actions

Actions Marketplace

As opposed to workflows that call actions, you can find a useful set of existing actions to call on the GitHub Marketplace in the Actions section. That’s available at the GitHub Marketplace. Figure 1-2 shows an example of this area in GitHub.

These are fully functional units that you can select from and use in your own workflows. Think of it as being like the plug-ins or other add-on modules that add functionality in other applications. As you’ll see in a later chapter, you can get to the Actions Marketplace from within the GitHub built-in environment for creating a workflow. You can easily browse and find actions here to save you time and effort versus having to code your own. (Creating your own actions is covered in Chapter 11.)

Figure 1-2. GitHub Actions Marketplace

As examples of the kinds of functionality you can find, the Marketplace has featured categories for interacting with IDEs, working on localization tasks, doing mobile development, and even working with project management tasks through applications such as JIRA. The actions on the Marketplace can be from GitHub or from other sources, such as individuals, organizations, or companies that want to integrate with Actions.

When you’re creating a new workflow, the Actions Marketplace is a great place to find existing actions that may already do what you need, thus saving you the effort of coding the functionality otherwise. And they’re also free. In fact, you can get started with GitHub Actions for free. But there are costs associated with certain levels of usage. I’ll cover more details on that in the next section.

What Costs Are Involved?

One of the first questions that comes to mind when any individual, team, or organization starts thinking about migrating to a new technology is the cost. With GitHub Actions, you may simply qualify for the free version. But if not, it’s important to have at least a basic understanding of how the paid model works so you’re not surprised.

The Free Model

GitHub Actions is free if either or both of the following two conditions are true:

• The repositories you use with actions are public.
• The systems you execute the actions on (the runners) are your own (rather than using the ones provided by GitHub).

That means if you are OK with having your GitHub repositories viewable by everyone, or if you can host the systems that will execute the code contained in the steps of the workflow, you can use the technology for free.

GitHub will not charge you to use self-hosted runners, but you will be required to install and run the runner application on your own servers. This is needed to allow GitHub Actions to communicate with your servers to execute your workflows. (Runners, including the process to create your own, are covered in Chapter 5.)

If the free model doesn’t fit the way you work, you’ll move into the paid model.

The Paid Model

Private repositories are ones with restricted access. Enterprise/corporate GitHub clients may frequently use this model, either via restricting access on the public GitHub site or by using an in-house or on-cloud GitHub instance restricted for their use.

There are two types of items you pay for with GitHub Actions:

• Storage: Actions allow you to store artifacts and packages on GitHub’s resources. After a certain point, the amount of storage you’re using for artifacts and packages will start to cost you.
• Minutes: Actions require processing time on virtual systems.

Artifacts and Packages

Artifacts refer to objects that you upload or generate through your workflows on GitHub. GitHub Packages are a convenient way to make things like containers and dependencies accessible.

For a private repository, you start with a certain amount of storage (for artifacts uploaded during processing of workflows) and minutes on runners that are free. After those are used up, you may be able to pay for and use more, or you may be cut off, depending on how you’re paying/billed by GitHub and the defaults for spending limits you have set up. (Artifacts are discussed in more detail in Chapter 7.)

If you’re paying/billed a regular amount monthly, after you’ve used up the free storage and minutes, by default, that’s it. You won’t be able to create new artifacts or do additional processing.

If, instead, you just get an invoice from GitHub for whatever amount of resources you’ve used during a billing period and pay that variable amount each time, by default you can continue to use (and pay for) more minutes and/or storage without limits.

Default Spending Limits

Default spending limits are referenced in the preceding discussion. Within GitHub, if you have access and authority to do so, those default spending limits can be changed through the settings for the type of account you have (user, organization, or enterprise). Changing them for an organization or enterprise requires that you are an owner or billing manager.

For machine usage on a system provided by GitHub, the compute cost is measured in the minutes you use on the runners. This accumulates as you use more compute but resets to 0 each month. The amount of storage you use accumulates as you store more artifacts but is not reset each month. So you just continue to pay the storage cost as long as you keep the artifacts around on GitHub.

Table 1-1 from GitHub’s documentation shows the breakdown of the free minutes and free storage you get per month, depending on your account type. This is current as of the time of this writing and subject to change. Always consult the official documentation for the latest pricing information.

Table 1-1. GitHub Actions pricing plans

Plan	Storage	Minutes (per month)
GitHub Free	500 MB	2,000
GitHub Pro	1 GB	3,000
GitHub Free for Organizations	500 MB	2,000
GitHub Team	2 GB	3,000
GitHub Enterprise Cloud	50 GB	50,000

The storage usage is calculated for each month based on hourly usage during the month.

Usage Rounding

For billing calculations, storage usage is rounded up to the nearest megabyte, and minute usage is rounded up to the nearest minute.

One other key factor to be aware of is that GitHub Actions charge more for jobs run on a system provided by GitHub if it requires a Windows or macOS system to execute. So, in a paid scenario, your cost to use one of those system versus a Linux system gets scaled up and you pay a premium, as shown in Table 1-2.

Table 1-2. Cost scaling per OS

Operating system	Minute multiplier
Linux	1
macOS	10
Windows	2

Table 1-3 shows an example of how the per-minute costs would compare for a process run on different kinds of systems (taken from GitHub’s documentation).

Table 1-3. Per-minute costs across OS

Operating system	Per-minute rate (USD)
Linux	$0.008
macOS	$0.08
Windows	$0.016

Current Cost Information

The information in the preceding tables is current as of the time of this writing and is subject to change. For the latest up-to-date information on costs around GitHub Actions, refer to the GitHub documentation.

The price you pay for use is certainly one factor to consider if you’re thinking about moving to GitHub Actions. But it should not be the only one. In the final section of this chapter, I’ll discuss how to decide when moving to GitHub Actions makes sense.

When Does Moving to GitHub Actions Make Sense?

Aside from price, what other factors are worth considering for moving to and using GitHub Actions? Here are a few that may be helpful.

Investment in GitHub

By definition, GitHub Actions are tightly bound to the GitHub ecosystem. They can only work when run through GitHub’s engine. So anyone needing to work with Actions will need to be familiar with, and comfortable working with, GitHub as an interface and environment.

And, if you are using your own runners to execute workflows and actions, you need to be comfortable with having the runner application installed on your systems.

Use of Public Actions

As discussed previously, GitHub Actions maintains a Marketplace for contributed actions. As with any public place where you can download components to pull in, you want to be sure that you are aware of what those actions are doing and that they meet your security requirements. In short, the responsibility for fit, purpose, and security when using a public action is yours.

Helpful Security Tips

Chapter 9 in this book covers security. But GitHub also has tips on securely using actions. See the GitHub documentation for more details.

Creating Your Own Actions

You have the flexibility to create and use your own actions. There are a couple of different types, as I discuss in Chapter 11. If you have already invested in creating custom functionality another way, you’ll need to learn the action structure and syntax. Then consider how you would either migrate to more action-based approaches or have a workflow invoke your existing functionality if feasible to do so. (Chapter 14 discusses approaches for migration.)

Artifact Management

GitHub Actions artifact management is convenient for quick, easy storage and sharing of artifacts. But it is not a package management system like GitHub Packages or Artifactory. There is a built-in retention period, after which artifacts are removed. If this is not suitable for your needs, you’ll need to establish another way to manage artifacts and connect your workflows to it.

Action Management

GitHub Actions provides a framework for creating and using actions to automate nearly anything. If you are in a corporate/enterprise environment, you may not want everyone creating and pulling in actions for shared repositories. Allowing this without proper controls could open security holes. Controls might take the form of making sure the set of actions used are approved and manageable. There should also be a regular update process to ensure any public actions used are kept up to date and use of them is reviewed as needed.

If employees are creating actions and sharing them for broader use, some sort of code review and standards should be in place. In short, since actions are written with code based in GitHub repositories, the same kinds of best practices you would use with other repositories in GitHub should also apply.

Enforcing Policies for Actions

For information on how to set policies within an enterprise or organization, see the Enterprise administrator documentation.

In general, the question of how much to invest in, and use, GitHub Actions comes down to how much you or your organization or enterprise want to gain the benefits of the new functionality, can migrate any needed existing functionality, and feel comfortable having your code and automation managed in this environment.

Conclusion

In this chapter, I’ve introduced GitHub Actions and shared some basic information about what the platform is for, its use cases and costs, and factors to consider when moving to it. GitHub Actions provides a full framework to automate the content you manage in GitHub. If you are invested in the GitHub ecosystem or considering moving to it, workflows and actions provide a good option for implementing automation such as CI/CD without having to rely on another application. As with any framework, the automation can be simple or complex. And while the underlying engine is provided by GitHub, there is an ever-growing community of users providing ready-made actions and workflows to draw on and lessen the setup/custom investment required.

Now that the basics of GitHub Actions have been explained, in the next chapter, I’ll dive in more to help you understand how actions work.