Adding self-hosted runners

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

In this article

Did this doc help you?

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 do not use self-hosted runners with public repositories.

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."

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.

  1. On GitHub, navigate to the main page of the repository.

  2. Under your repository name, click Settings.

    Repository settings button

  3. In the left sidebar, click Actions.

    Actions setting

  4. Under "Self-hosted runners," click Add runner.

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

    Select self-hosted runner operating system

  6. 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 and ready to receive jobs, you will see the following message on 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.

  1. On GitHub, navigate to the main page of the organization.

  2. Under your organization name, click Settings.

    Organization settings button

  3. In the left sidebar, click Actions.

    Actions setting

  4. Under "Self-hosted runners," click Add new, then click New runner.

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

    Select self-hosted runner operating system

  6. 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 and ready to receive jobs, you will see the following message on 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 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.

To add a self-hosted runner to an enterprise account, you must be an enterprise owner.

  1. Navigate to your enterprise account by visiting https://github.com/enterprises/ENTERPRISE-NAME, replacing ENTERPRISE-NAME with your enterprise account's name.

  2. In the enterprise sidebar, click Policies.

    Policies tab in the enterprise account sidebar

  3. Under " Policies", click Actions.

  4. Click the Self-hosted runners tab.

  5. Click Add new, then click New runner. 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."

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

    Select self-hosted runner operating system

  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 and ready to receive jobs, you will see the following message on 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."

Did this doc help you?