Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.
All products
GitHub Actions

This version of GitHub Enterprise was discontinued on 2023-03-15. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

Adding self-hosted runners

In this article

You can add a self-hosted runner to a repository, an organization, or an enterprise.

Note: GitHub-hosted runners are not currently supported on GitHub Enterprise Server. You can see more information about planned future support on the GitHub public roadmap.

You can add a self-hosted runner to a repository, an organization, or an enterprise.

If you are an organization or enterprise administrator, you might want to add your self-hosted runners at the organization or enterprise level. This approach makes the runner available to multiple repositories in your organization or enterprise, and also lets you to manage your runners in one place.

For information on supported operating systems for self-hosted runners, or using self-hosted runners with a proxy server, see "About self-hosted runners."

Warning: We recommend that you only use self-hosted runners with private repositories. This is because forks of your public repository can potentially run dangerous code on your self-hosted runner machine by creating a pull request that executes the code in a workflow.

For more information, see "About self-hosted runners."

You can set up automation to scale the number of self-hosted runners. For more information, see "Autoscaling with self-hosted runners."

Prerequisites

  • GitHub Actions must be enabled for GitHub Enterprise Server. A site administrator can enable and configure GitHub Actions for your instance. For more information, see "Getting started with GitHub Actions for GitHub Enterprise Server."

  • You must have access to the machine you will use as a self-hosted runner in your environment.

  • The connection between self-hosted runners and GitHub Enterprise Server is over HTTP (port 80) or HTTPS (port 443). To ensure connectivity over HTTPS, configure TLS for your GitHub Enterprise Server instance. For more information, see "Configuring TLS." For more information, see "About self-hosted runners."

Adding a self-hosted runner to a repository

You can add self-hosted runners to a single repository. To add a self-hosted runner to a user repository, you must be the repository owner. For an organization repository, you must be an organization owner or have admin access to the repository. For information about how to add a self-hosted runner with the REST API, see "Actions."

  1. On your GitHub Enterprise Server instance, navigate to the main page of the repository.

  2. Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

    Screenshot of a repository header showing the tabs. The "Settings" tab is highlighted by a dark orange outline.

  3. In the left sidebar, click Actions.

  4. In the left sidebar, under "Actions", click Runners.

  5. Click New self-hosted runner.

  6. Select the operating system image and architecture of your self-hosted runner machine.

  7. You will see instructions showing you how to download the runner application and install it on your self-hosted runner machine.

    Open a shell on your self-hosted runner machine and run each shell command in the order shown.

    Note: On Windows, if you want to install the self-hosted runner application as a service, you must open a shell with administrator privileges. We also recommend that you use C:\actions-runner as the directory for the self-hosted runner application so that Windows system accounts can access the runner directory.

    The instructions walk you through completing these tasks:

    • Downloading and extracting the self-hosted runner application.
    • Running the config script to configure the self-hosted runner application and register it with GitHub Actions. The config script requires the destination URL and an automatically-generated time-limited token to authenticate the request.
    • Running the self-hosted runner application to connect the machine to GitHub Actions.

Checking that your self-hosted runner was successfully added

After completing the steps to add a self-hosted runner, the runner and its status are now listed under "Self-hosted runners".

The self-hosted runner application must be active for the runner to accept jobs. When the runner application is connected to GitHub Enterprise Server and ready to receive jobs, you will see the following message on the machine's terminal.

√ Connected to GitHub

2019-10-24 05:45:56Z: Listening for Jobs

For more information, see "Monitoring and troubleshooting self-hosted runners."

Adding a self-hosted runner to an organization

You can add self-hosted runners at the organization level, where they can be used to process jobs for multiple repositories in an organization. To add a self-hosted runner to an organization, you must be an organization owner. For information about how to add a self-hosted runner with the REST API, see "Actions."

  1. On your GitHub Enterprise Server instance, navigate to the main page of the organization.

  2. Under your organization name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

    Screenshot of the horizontal navigation bar for an organization. The "Settings" tab is outlined in dark orange.

  3. In the left sidebar, click Actions.

  4. In the left sidebar, under "Actions", click Runners.

  5. Click New runner.

  6. Select the operating system image and architecture of your self-hosted runner machine.

  7. You will see instructions showing you how to download the runner application and install it on your self-hosted runner machine.

    Open a shell on your self-hosted runner machine and run each shell command in the order shown.

    Note: On Windows, if you want to install the self-hosted runner application as a service, you must open a shell with administrator privileges. We also recommend that you use C:\actions-runner as the directory for the self-hosted runner application so that Windows system accounts can access the runner directory.

    The instructions walk you through completing these tasks:

    • Downloading and extracting the self-hosted runner application.
    • Running the config script to configure the self-hosted runner application and register it with GitHub Actions. The config script requires the destination URL and an automatically-generated time-limited token to authenticate the request.
    • Running the self-hosted runner application to connect the machine to GitHub Actions.

Checking that your self-hosted runner was successfully added

After completing the steps to add a self-hosted runner, the runner and its status are now listed under "Self-hosted runners".

The self-hosted runner application must be active for the runner to accept jobs. When the runner application is connected to GitHub Enterprise Server and ready to receive jobs, you will see the following message on the machine's terminal.

√ Connected to GitHub

2019-10-24 05:45:56Z: Listening for Jobs

For more information, see "Monitoring and troubleshooting self-hosted runners."

Note: For security reasons, public repositories can't use runners in a runner group by default, but you can override this in the runner group's settings. For more information, see "Managing access to self-hosted runners using groups."

Adding a self-hosted runner to an enterprise

You can add self-hosted runners to an enterprise, where they can be assigned to multiple organizations. The organization admins are then able to control which repositories can use it.

New runners are assigned to the default group. You can modify the runner's group after you've registered the runner. For more information, see "Managing access to self-hosted runners using groups."

To add a self-hosted runner to an enterprise, you must be an enterprise owner. For information about how to add a self-hosted runner with the REST API, see the enterprise endpoints in the GitHub Actions REST API.

  1. In the top-right corner of GitHub Enterprise Server, click your profile photo, then click Enterprise settings.

    Screenshot of the drop-down menu that appears when you click the profile photo on GitHub Enterprise Server. The "Enterprise settings" option is highlighted in a dark orange outline.

  2. In the enterprise account sidebar, click Policies.

  3. Under " Policies", click Actions.

  4. Click the Runners tab.

  5. Click New runner.

  6. Select the operating system image and architecture of your self-hosted runner machine.

  7. You will see instructions showing you how to download the runner application and install it on your self-hosted runner machine.

    Open a shell on your self-hosted runner machine and run each shell command in the order shown.

    Note: On Windows, if you want to install the self-hosted runner application as a service, you must open a shell with administrator privileges. We also recommend that you use C:\actions-runner as the directory for the self-hosted runner application so that Windows system accounts can access the runner directory.

    The instructions walk you through completing these tasks:

    • Downloading and extracting the self-hosted runner application.
    • Running the config script to configure the self-hosted runner application and register it with GitHub Actions. The config script requires the destination URL and an automatically-generated time-limited token to authenticate the request.
    • Running the self-hosted runner application to connect the machine to GitHub Actions.

Checking that your self-hosted runner was successfully added

After completing the steps to add a self-hosted runner, the runner and its status are now listed under "Self-hosted runners".

The self-hosted runner application must be active for the runner to accept jobs. When the runner application is connected to GitHub Enterprise Server and ready to receive jobs, you will see the following message on the machine's terminal.

√ Connected to GitHub

2019-10-24 05:45:56Z: Listening for Jobs

For more information, see "Monitoring and troubleshooting self-hosted runners."

Note: For security reasons, public repositories can't use runners in a runner group by default, but you can override this in the runner group's settings. For more information, see "Managing access to self-hosted runners using groups."

Making enterprise runners available to repositories

By default, runners in an enterprise's "Default" self-hosted runner group are available to all organizations in the enterprise, but are not available to all repositories in each organization.

To make an enterprise-level self-hosted runner group available to an organization repository, you might need to change the organization's inherited settings for the runner group to make the runner available to repositories in the organization.

For more information on changing runner group access settings, see "Managing access to self-hosted runners using groups."

Further reading