{"id":106189,"date":"2025-04-18T21:14:28","date_gmt":"2025-04-18T21:14:28","guid":{"rendered":"https:\/\/www.red-gate.com\/simple-talk\/?p=106189"},"modified":"2026-07-08T08:33:47","modified_gmt":"2026-07-08T08:33:47","slug":"introduction-to-github-actions-part-2-github-hosted-runners","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/devops\/introduction-to-github-actions-part-2-github-hosted-runners\/","title":{"rendered":"How to use GitHub-hosted runners in GitHub Actions (complete guide)"},"content":{"rendered":"\n

GitHub-hosted runners are virtual machines managed by GitHub that execute your GitHub Actions workflows, so you don’t have to provision or maintain your own infrastructure. They’re available in Linux, Windows, and macOS versions, come with many common tools pre-installed, and are typically free to use on public repositories.<\/strong><\/p>\n\n\n\n

In this guide, learn how to choose and specify a runner, run multiple jobs with dependencies between them, install additional tools (like Redgate Flyway) when they aren’t available by default, and use Docker containers to run software with zero manual setup. By the end, you’ll know when a GitHub-hosted runner is the right choice \u2014 and when you might need a self-hosted one instead.<\/strong><\/p>\n\n\n\n

Introduction<\/h2>\n\n\n\n

In my earlier guide<\/a>, you learned how to set up a GitHub Actions Workflow in a GitHub repository. Like learning many languages and technologies, we started out with code that printed a \u201cHello, World!\u201d message. This process verifies that it\u2019s possible to run a basic script.<\/p>\n\n\n\n

The \u201cHello, World\u201d script ran on a Linux VM provided by GitHub. Workflow code must run on a server, called a Runner<\/em>. In this article, you\u2019ll learn about the many options for using a GitHub-hosted runner, including Docker.<\/p>\n\n\n\n

GitHub runner options<\/h2>\n\n\n\n

There are two main options for runners: self-hosted and GitHub-hosted. Each option has its benefits and drawbacks.<\/p>\n\n\n\n

What are GitHub-hosted runners?<\/h3>\n\n\n\n

When running your workflow on a GitHub-hosted runner, you have the choice of Linux, Windows, and macOS. See this documentation page<\/a> to see the list of supported operating systems.<\/p>\n\n\n\n

The GitHub-hosted runners are inexpensive to use, and typically free when using public repositories. This is why we left our test repository public). See this GitHub docs page<\/a> for more information about billing when using private repos. Be sure to review the options, as different types of accounts have different time limits, measured in minutes per month. Linux runners are the least expensive to run.<\/p>\n\n\n\n

The other benefit is that GitHub manages the runners for you. You do not need to worry about upgrades or patching, including the software installed on the images.<\/p>\n\n\n\n

The downside is that you may need to install some tools during the run. Thankfully, there are many utilities installed by default. If you need something specific that\u2019s not installed, such as Redgate Flyway<\/a>, you can always create a Docker image with everything you need and just run the workflow on your Docker container.<\/p>\n\n\n\n

GitHub-hosted runners live in the cloud, so any resources needed, such as a database server must be available to the runner. That means you may need to open certain ports or create network security groups, but it might not be possible to use GitHub-hosted runners for certain workloads, such as deploying database code.<\/p>\n\n\n\n

There are also larger VMs available<\/a> with advanced features if you have specific workloads or use cases that require more resources.<\/p>\n\n\n\n

What are GitHub self-hosted runners?<\/h3>\n\n\n\n

The other option is using virtual machines that you maintain either in a data center or in the cloud provider of your choice. The benefit is that you can tailor the operating system and tools to your exact specifications. Working through security requirements for accessing databases or other resources should be much easier than by using the GitHub-hosted runners.<\/p>\n\n\n\n

The main downside of using your own runners is that you will need to maintain them and the software that is installed. You will most likely pay for licensing and storage of the VMs, but GitHub doesn\u2019t charge you for the minutes that they run.<\/p>\n\n\n\n

Learn all about GitHub self-hosted runners in my detailed guide here<\/a>.<\/p>\n\n\n\n

How to specify a GitHub runner<\/h2>\n\n\n\n

The first article demonstrated how to run this \u201cHello, World\u201d workflow:<\/p>\n\n\n\n

name: Hello, World\n\n# Controls when the workflow will run, in this case manually\non: workflow_dispatch\njobs:\n  PrintHelloWorld:\n    name: Print Hello, World!\n    runs-on: ubuntu-latest\n    steps:\n    - run: echo \"Hello, World!\"<\/pre><\/div>\n\n\n\n
In the jobs:<\/strong> section, you can specify one or more jobs and one or more steps in each job. In this case, there is one job with one step. Notice the runs-on:<\/strong> code in the job specifying ubuntu-latest<\/code>. This line in the code tells GitHub Actions to spin up a VM for running this workflow.<\/p>\n\n\n\n
Instead of running on the latest version of ubuntu, you could run the job on any supported version of Ubuntu, Windows or, macOS. (See the documentation<\/a> for the list of possible operating systems).<\/p>\n\n\n\n
Notice that the runner is specified at the job level. The same runner will be used for all steps in the job, but a different runner will be created for the next job if there is one.<\/p>\n\n\n\n
This example saves \u201cHello, World\u201d to a file instead of displaying it. The next step runs a directory listing. Finally, a new job also runs a listing. You can find the code for this article here<\/a>.<\/p>\n\n\n\n
name: Hello, World \n# Controls when the workflow will run, in this case manually\non: workflow_dispatch\n\njobs:\n  PrintHelloWorld:\n    name: Print Hello, World!\n    runs-on: ubuntu-latest\n    steps:\n    - run: echo \"Hello, World!\" > file.txt\n    - run: ls\n  PrintDirectory:\n    name: Print directory\n    needs: PrintHelloWorld\n    runs-on: ubuntu-latest\n    steps:\n    - run: ls<\/pre><\/div>\n\n\n\n
Note that you can edit the script locally in VS Code and then commit\/push it to the repo. It\u2019s also possible to edit the file directly in GitHub.<\/p>\n\n\n\n
After running the workflow and clicking on the run, you\u2019ll see the two jobs:<\/p>\n\n\n\n
\"An
Job steps.<\/em><\/figcaption><\/figure>\n\n\n\n
Notice that there is also a dependency created by the needs:<\/strong> statement. Print Directory<\/code> cannot run unless Print Hello, World!<\/code> is successful.<\/p>\n\n\n\n
Drilling down into the first job, you\u2019ll see that the file was created.<\/p>\n\n\n\n
\"An
The file was created<\/em>.<\/figcaption><\/figure>\n\n\n\n
Notice that the second job doesn\u2019t return the file because this job is running in a new VM.<\/p>\n\n\n\n
\"An
The second job uses a new VM.<\/em><\/figcaption><\/figure>\n\n\n\n
You can even use different operating systems for specific jobs if you have the need.<\/p>\n\n\n\n
How to install tools on a GitHub-hosted runner<\/h2>\n\n\n\n
As mentioned, there are utilities already available on GitHub-hosted runners<\/a>, but you may not have everything you need. For example, you may want to run something like Redgate Flyway Community<\/a> to deploy database changes. You can install tools by running commands as job steps.<\/p>\n\n\n\n
This new workflow installs Flyway Community (code from the Flyway docs<\/a>) and then tests to see that it\u2019s in place. Be sure to save the new file in the .github\\workflows folder and use the yml or yaml extension.<\/p>\n\n\n\n
name: Install Flyway\non: workflow_dispatch\n\njobs:\n  Install:\n    name: Install Flyway\n    runs-on: ubuntu-latest\n    steps:\n      - name: Install\n        run: wget -qO- https:\/\/download.red-gate.com\/maven\/release\/com\/redgate\/flyway\/flyway-commandline\/11.1.1\/flyway-commandline-11.1.1-linux-x64.tar.gz | tar -xvz && sudo ln -s `pwd`\/flyway-11.1.1\/flyway \/usr\/local\/bin\n      - name: Check Install\n        run: flyway --version<\/pre><\/div>\n\n\n\n
After creating and running the new workflow, you should see results similar to this:<\/p>\n\n\n\n
\"An
Installing Flyway results.<\/em><\/figcaption><\/figure>\n\n\n\n
If you added the job steps to the same job, you could run additional Flyway commands to deploy your database code.<\/p>\n\n\n\n
How to use Docker on a GitHub-hosted runner<\/h2>\n\n\n\n
Running a Docker container on the GitHub-hosted runner is a convenient option when you need software installed on the runner. You can use images managed by the software vendor or create an image yourself.<\/p>\n\n\n\n
NOTE: Creating Docker images is beyond the scope of this article series.<\/p>\n\n\n\n
For example, If you need Flyway, you can just use one of the images created by Redgate for Community<\/a> or Paid editions<\/a>.<\/p>\n\n\n\n
Create this new workflow that runs Flyway in a Docker container. Be sure that the file extension is yml or yaml and that you save it in .github\\workflows. Notice that the only addition to the code is the container:<\/strong> line specifying the name of the image.<\/p>\n\n\n\n
name: Run Flyway on Docker\non:   workflow_dispatch\n\njobs:\n  runFlyway:\n    name: Run Flyway\n    runs-on: ubuntu-latest\n    container: flyway\/flyway\n    steps:\n    - name: runFlyway\n      run: flyway --version<\/pre><\/div>\n\n\n\n
After running the file, check the results. You\u2019ll see results similar to this:<\/p>\n\n\n\n
\"An
The results of running Redgate Flyway in a Docker container<\/em>.<\/figcaption><\/figure>\n\n\n\n
Conclusion<\/h2>\n\n\n\n
This article covered how to use Git-Hub hosted runners in your workflows. This is the most convenient way to run workflows if the VMs will meet your security requirements. You can choose from several versions of Ubuntu or Windows, and even macOS. These VMs have utilities installed, but it\u2019s easy to install any other required tools. One of the best options is using Docker images from the software vendor.<\/p>\n\n\n\n
\n    
\n        
\n            
\n                
Subscribe to the Simple Talk newsletter<\/h3>\n                
\n                                            Get selected articles, event information, podcasts and other industry content delivered straight to your inbox.                                    <\/div>\n            <\/div>\n                                            Subscribe<\/a>\n                    <\/div>\n    <\/div>\n<\/section>\n\n\n
\n    
FAQs: GitHub-hosted runners<\/h2>\n\n                        
1. What is a GitHub-hosted runner?<\/h3>\n            
\n                
A GitHub-hosted runner is a virtual machine that GitHub provisions, manages, and patches on your behalf to execute the jobs in a GitHub Actions workflow. It comes with many common development tools pre-installed and supports Linux, Windows, and macOS.<\/p>\n            <\/div>\n                    
2. Are GitHub-hosted runners free?<\/h3>\n            
\n                
They’re typically free to use on public repositories, with usage measured in minutes per month for private repos depending on your account type. Linux runners are the least expensive option, and larger, more powerful VMs are also available for demanding workloads.<\/p>\n            <\/div>\n                    
3. How do I specify which operating system a job runs on?<\/h3>\n            
\n                
Use the runs-on:<\/code> key at the job level in your workflow YAML file (e.g., runs-on: ubuntu-latest<\/code>). Each job can specify a different operating system, and the runner applies to every step within that job.<\/p>\n            <\/div>\n                    
4. Can I install additional tools that aren't available by default on a GitHub-hosted runner?<\/h3>\n            
\n                
Yes. You can add a job step that installs the tool via a command (like wget<\/code> or a package manager) before it’s needed. Alternatively, you can run the job inside a Docker container that already has the required software pre-installed.<\/p>\n            <\/div>\n                    
5. What's the main drawback of GitHub-hosted runners compared to self-hosted ones?<\/h3>\n            
\n                
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
Since they run in the cloud, any resources they need \u2014 like a database server \u2014 must be network-accessible to them, which may require opening ports or configuring security groups. Self-hosted runners avoid this by running on infrastructure you control.<\/p>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n            <\/div>\n            <\/section>\n","protected":false},"excerpt":{"rendered":"
Learn how GitHub-hosted runners work in GitHub Actions \u2014 compare OS options, install custom tools like Flyway, and run workflows in Docker containers.…<\/p>\n","protected":false},"author":110218,"featured_media":106195,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":true,"footnotes":""},"categories":[143512,53],"tags":[5970,5775,159280],"coauthors":[11292],"class_list":["post-106189","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devops","category-featured","tag-devops","tag-github","tag-kathikellenbergergithubseries"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/106189","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/users\/110218"}],"replies":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/comments?post=106189"}],"version-history":[{"count":3,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/106189\/revisions"}],"predecessor-version":[{"id":111742,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/106189\/revisions\/111742"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/media\/106195"}],"wp:attachment":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/media?parent=106189"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/categories?post=106189"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/tags?post=106189"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/coauthors?post=106189"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}