Enable Self-Hosted Runners on GitHub

Why is this needed?

GitHub blocks self-hosted runners by default at the org level for security. This is a one-time configuration so machine.dev runners (which appear to GitHub as ephemeral self-hosted runners) can pick up your jobs.

Before you can use machine.dev, configure your GitHub organization or account to allow self-hosted runners. This page walks through the GitHub settings click-by-click.

If your jobs are being queued but no runners pick them up, you almost certainly need to enable self-hosted runner access here.

Prerequisites

• You must be an organization owner or have the “Manage organization Actions policies” permission
• For personal accounts, you need admin access to your repositories

Enabling Self-Hosted Runners for Organizations

Step 1: Access Organization Settings

1. In the upper-right corner of GitHub, click your profile picture
2. Click Your organizations
3. Next to your organization name, click Settings

Step 2: Navigate to Actions Settings

1. In the left sidebar, click Actions
2. Click General

Step 3: Configure Runner Policies

Scroll down to the “Runners” section. You’ll see a dropdown menu with three options:

Recommended: Select “All repositories” to allow machine.dev runners to work with any repository in your organization.

If you choose “Selected repositories”:

1. Click the selection button that appears
2. Check the boxes for repositories that should have access to machine.dev runners
3. Click Select repositories

Step 4: Save Changes

Your changes are saved automatically when you make a selection.

Enabling Self-Hosted Runners for Public Repositories

If you want to use machine.dev runners with public repositories, you need to configure additional settings in Runner Groups.

Step 1: Access Runner Groups

1. Go to your organization’s Settings
2. In the left sidebar, click Actions
3. Click Runner groups

Or navigate directly to: https://github.com/organizations/YOUR-ORG-NAME/settings/actions/runner-groups

Step 2: Configure the Default Runner Group

1. Click on the Default runner group (or the group you want to configure)
2. Look for the “Allow public repositories” option
3. Enable this setting if you want public repositories to use self-hosted runners

Security Consideration

GitHub recommends using self-hosted runners only with private repositories. Public repositories can receive pull requests from forks, which could potentially run untrusted code on your runners. machine.dev runners are ephemeral and isolated, which mitigates many of these risks, but you should still consider your security requirements.

Enabling Self-Hosted Runners for Personal Accounts

For personal accounts (not organizations), self-hosted runners are typically enabled by default at the repository level.

Step 1: Access Repository Settings

1. Navigate to your repository on GitHub
2. Click Settings
3. In the left sidebar, click Actions
4. Click General

Step 2: Verify Runner Settings

Under the “Runners” section, ensure that self-hosted runners are not disabled.

Enterprise Considerations

If your organization is part of a GitHub Enterprise, there may be enterprise-level policies that override organization settings.

• Enterprise administrators can enforce policies that restrict self-hosted runner usage
• If you cannot modify runner settings at the organization level, contact your enterprise administrator
• Enterprise-level runner groups can be shared across multiple organizations

Troubleshooting

”No runner matching the specified labels was found”

This error typically means:

1. Self-hosted runners are disabled for your repository
2. The repository doesn’t have access to the runner group
3. For public repos: “Allow public repositories” is not enabled in runner groups

Solution: Follow the steps above to enable self-hosted runner access.

Settings Are Grayed Out

If the runner settings are grayed out or you cannot modify them:

• Check if enterprise-level policies are overriding your settings
• Verify you have the required permissions (organization owner or “Manage organization Actions policies”)
• Contact your GitHub Enterprise administrator if applicable

Runner Shows as “Disabled”

If you previously had runners that now show as “Disabled”:

• This happens when you change the runner policy to “Disabled” or remove repository access
• Re-enable the policy or add the repository back to the allowed list

Next Steps

Once you’ve enabled self-hosted runners on GitHub:

• Run the Quickstart — first job in 5 minutes
• Browse GPU runners and CPU runners
• See Workflow setup patterns

Additional Resources

• GitHub Docs: Disabling or limiting GitHub Actions
• GitHub Docs: Managing access to self-hosted runners using groups