Skip to main content


GitHub – On-Prem Server Connectivity Using Self-Hosted Runners

Developers Discussing Programming Code

Various deployment methods, including cloud-based (e.g., CloudHub) and on-premises, are available to meet diverse infrastructure needs. GitHub, among other tools, supports versioning and code backup, while CI/CD practices automate integration and deployment processes, enhancing code quality and speeding up software delivery.

GitHub Actions, an automation platform by GitHub, streamlines building, testing, and deploying software workflows directly from repositories. Although commonly associated with cloud deployments, GitHub Actions can be adapted for on-premises setups with self-hosted runners. These runners serve as the execution environment, enabling deployment tasks on local infrastructure.

Configuring self-hosted runners allows customization of GitHub Actions workflows for on-premises deployment needs. Workflows can automate tasks like Docker image building, artifact pushing to private registries, and application deployment to local servers.

Leveraging GitHub Actions for on-premises deployment combines the benefits of automation, version control, and collaboration with control over infrastructure and deployment processes.

What is a Runner?

A runner refers to the machine responsible for executing tasks within a GitHub Actions workflow. It performs various tasks defined in the action script, like cloning the code directory, building the code, testing the code, and installing various tools and software required to run the GitHub action workflow.

There are 2 Primary Types of Runners:

  1. GitHub Hosted Runners:

    These are virtual machines provided by GitHub to run workflows. Each machine comes pre-configured with the environment, tools, and settings required for GitHub Actions. GitHub-hosted runners support various operating systems, such as Ubuntu Linux, Windows, and macOS.

  2. Self-Hosted Runners:

    A self-hosted runner is a system deployed and managed by the user to execute GitHub Actions jobs. Compared to GitHub-hosted runners, self-hosted runners offer more flexibility and control over hardware, operating systems, and software tools. Users can customize hardware configurations, install software from their local network, and choose operating systems not provided by GitHub-hosted runners. Self-hosted runners can be physical machines, virtual machines, containers, on-premises servers, or cloud-based instances.

Why Do We Need a Self-hosted Runner?

Self-hosted runners play a crucial role in deploying applications on the on-prem server using GitHub Action Scripts and establishing connectivity with an on-prem server. These runners can be created at different management levels within GitHub: repository, organization, and enterprise.

By leveraging self-hosted runners for deployment, organizations can optimize control, customization, performance, and cost-effectiveness while meeting compliance requirements and integrating seamlessly with existing infrastructure and tools. Here are few advantages of self-hosted runners as given below.

  1. Control and Security:

    Self-hosted runners allow organizations to maintain control over their infrastructure and deployment environment. This includes implementing specific security measures tailored to the organization’s requirements, such as firewall rules and access controls.

  2. Customization:

    With self-hosted runners, you have the flexibility to customize the hardware and software environment to match your specific needs. This can include installing specific libraries, tools, or dependencies required for your applications or services.

  3. Performance:

    Self-hosted runners can offer improved performance compared to cloud-based alternatives, especially for deployments that require high computational resources or low-latency connections to local resources.

  4. Cost Management:

    While cloud-based solutions often incur ongoing costs based on usage and resource consumption, self-hosted runners can provide cost savings by utilizing existing infrastructure without incurring additional cloud service charges.

  5. Compliance:

    For organizations operating in regulated industries or regions with strict compliance requirements, self-hosted runners offer greater control and visibility over where code is executed and how data is handled, facilitating compliance efforts.

  6. Offline Deployment:

    In environments where internet connectivity is limited or unreliable, self-hosted runners enable deployment workflows to continue functioning without dependency on external cloud services or repositories.

  7. Scalability:

    Self-hosted runners can be scaled up or down according to demand, allowing organizations to adjust resource allocation based on workload fluctuations or project requirements.

  8. Integration with Existing Tools:

    Self-hosted runners seamlessly integrate with existing on-premises tools and infrastructure, facilitating smoother adoption and interoperability within the organization’s ecosystem.

Getting Started With a Self-hosted Runner

Follow the steps below to create and utilize a self-hosted runner.

Repository Level Self-hosted Runner:

  1. Log in to your GitHub account and navigate to the desired repository.
  2. Go to the repository’s settings tab and select the “Runners” menu under the “Actions” menu.
    Step 1
  3. Click on the “New self-hosted runner” button to initiate the creation process.
    Image 2
  4. Based on your system requirements, choose the appropriate runner image. For instance, if your self-hosted runner will run on Windows, select the Windows runner image.
    Image 3
  5. Open Windows PowerShell and execute the following command to create the actions-runner folder:
    mkdir actions-runner; cd actions-runner
  6. Download the latest runner package by running the following command:
    Invoke-WebRequest -Uri -OutFile
  7. Extract the downloaded package and configure the self-hosted runner according to your deployment needs.
    Add-Type -AssemblyName System.IO.Compression.FileSystem ; [System.IO.Compression.ZipFile]::ExtractToDirectory("$PWD/", "$PWD")
  8. Configure the runner using the below command. Replace the placeholder with actual values.
    ./config.cmd --url<owner>/<repo_name> --token <token>
  9. To run the runner, use the below command.
  10. Now your self-hosted runner is ready to use in your GitHub action script.
    # Use below YAML code snippet in your workflow file for each job
    runs-on: self-hosted

    Image 4

Organization Level and Enterprise Level Self-hosted Runners:

The process for creating organization-level and enterprise-level self-hosted runners follows similar steps. Still, the runners created at these levels can serve multiple repositories or organizations within the account. The setup process generally involves administrative permissions and configuration at a broader level.

By following these steps, you can set up self-hosted runners to enable connectivity between your on-prem server and GitHub Action Scripts, facilitating on-prem deployments seamlessly.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Avinash Rathod

Avinash Rathod is a Lead Technical consultant at Perficient, Nagpur. He has over 5 years of industry experience and working as a Lead Integration Developer having expertise in MuleSoft, Workato, Java. Avinash is also a MuleSoft Certified Platform Architect.

More from this Author

Follow Us