> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Demo Self Hosted Runner

> Guide to create, register, and manage a Linux self-hosted GitHub Actions runner and runner group, with configuration, security, and workflow targeting

In this lesson we create and register a Linux self-hosted runner for GitHub Actions and attach it to an enterprise runner group so workflows can target your own infrastructure. This guide assumes your enterprise policy already permits the Actions you need.

![A dark-mode screenshot of a GitHub Enterprise settings page for the "NextGen Gaming" organization, showing the Policies → Actions settings. The panel lists options for enabling Actions, choosing which actions/reusable workflows are allowed, and related checkboxes and input fields.](https://mintcdn.com/kodekloud-c4ac6d9a/Ae2SeWV4btujbkSt/images/GitHub-Administration-Certification/GitHub-Actions-and-Runners/Demo-Self-Hosted-Runner/github-enterprise-nextgen-gaming-actions-settings.jpg?fit=max\&auto=format\&n=Ae2SeWV4btujbkSt\&q=85\&s=59bae7ab30cc2e7fa5df08967a6a5509)

Overview: runners vs runner groups

* A GitHub runner is the machine (VM, container, or physical host) that executes CI/CD jobs for Actions.
* Runner groups are organizational constructs that group and control self-hosted runners (which repositories can use them, visibility, etc.).

| Concept | Purpose | Notes |
| - | - | - |
| Runner | Executes Actions jobs (VM, container, physical host) | Installed and configured on the host machine |
| Runner group | Controls access, visibility, and repository assignment for self-hosted runners | Groups let you restrict which repos can use specific runners |

We’ll create a runner group named `production-shared-group`, register a Linux self-hosted runner into that group, and then target it from a workflow. The enterprise provides a default group, but using custom groups helps apply least-privilege access and better management.

For production environments, restrict which repositories can use runner groups and apply least-privilege policies. Avoid enabling self-hosted runners for public repositories unless absolutely necessary.

**Create a Warning about public repos**

Allowing self-hosted runners for public repositories is a security risk: anyone can fork a public repo and trigger workflows that execute arbitrary code on your runners. Use caution and avoid enabling this unless you have strict controls.

Create and register a Linux self-hosted runner
Follow these steps on a Linux VM (Ubuntu example). Replace the `--url` and `--token` values with the ones provided by your GitHub Enterprise or organization runner setup page.

1. Create a working directory and download the runner package

```bash theme={null}
# Create a folder and change into it
mkdir actions-runner && cd actions-runner

# Download the latest runner package (version shown here as an example)
curl -o actions-runner-linux-x64-2.336.0.tar.gz -L https://github.com/actions/runner/releases/download/v2.336.0/actions-runner-linux-x64-2.336.0.tar.gz
```

2. (Optional) Validate checksum

```bash theme={null}
# Optional: Validate the SHA-256 checksum
echo "04cf0be1aff4c3ec3554466c39124ca250e3effd8873bb7e8d68535aa9505d5d  actions-runner-linux-x64-2.336.0.tar.gz" | shasum -a 256 -c
```

3. Extract the runner and configure it

```bash theme={null}
# Extract the installer
tar xzf ./actions-runner-linux-x64-2.336.0.tar.gz

# Configure the runner (example uses enterprise URL and token)
# Replace the --url and --token values with the ones provided by GitHub Enterprise or the org
./config.sh --url https://github.com/enterprises/nextgen-gaming --token CMJIMVTUVPKPNAW7JWBYI7H3KRVAFF
```

During `./config.sh` you will be prompted for the runner group, runner name, and optional labels. Example interactive responses:

```text theme={null}
# Authentication
√ Connected to GitHub

# Runner Registration
Enter the name of the runner group to add this runner to: [press Enter for Default] production-shared-group
Enter the name of runner: [press Enter for SilentShadow] prod-linux

This runner will have the following labels: 'self-hosted', 'Linux', 'X64'
Enter any additional labels (ex. label-1,label-2): [press Enter to skip] prod-ubuntu

√ Runner successfully added

# Runner settings
Enter name of work folder: [press Enter for _work]
√ Settings Saved.
```

4. Start the runner process (keeps the runner listening for jobs)

```bash theme={null}
# Start the runner so it listens for jobs
./run.sh
```

After starting, the runner will connect and show it is listening for jobs:

```text theme={null}
✓ Connected to GitHub
Current runner version: '2.336.0'
2026-08-25 06:15:41Z: Listening for Jobs
```

Assigning repositories to the runner group
Edit the runner group settings at the enterprise or organization level (for `production-shared-group`) to explicitly allow the repositories that should be able to use runners in that group. By default no repositories may have access — you must add repositories (or allow all) to grant access.

Use the organization Actions → Runners view to confirm the runner appears and to inspect its labels. Labels are used to match jobs to specific runners.

![A screenshot of a GitHub organization settings page (game-devstudio) showing the Actions → Runners view with a self-hosted runner named "prod-linux" listed as Idle. The left sidebar navigation and a "New runner" button are also visible.](https://mintcdn.com/kodekloud-c4ac6d9a/Ae2SeWV4btujbkSt/images/GitHub-Administration-Certification/GitHub-Actions-and-Runners/Demo-Self-Hosted-Runner/github-actions-runners-prod-linux.jpg?fit=max\&auto=format\&n=Ae2SeWV4btujbkSt\&q=85\&s=0d3f57ebac57e62e674d7ce0c973b3ec)

Example workflow: target the self-hosted runner
Use `runs-on` with `self-hosted` plus any custom labels you defined (for example `prod-ubuntu`) to route jobs to this runner.

```yaml theme={null}
name: Using Composite Workflow

on:
  push:
  workflow_dispatch:

jobs:
  test-composite-action:
    runs-on: [self-hosted, prod-ubuntu]
    steps:
      - uses: actions/checkout@v4.4.0
      - uses: ./composite-action
        with:
          environment: 'production'
      # Example additional steps you might add:
      # - uses: some-random/action@v2
      # - name: Super-linter
      #   uses: super-linter/super-linter@v8.7.0 # x-release-please-version
      #   env:
      #     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      # - name: PR Agent action step
      #   uses: the-pr-agent/pr-agent@main
      #   env:
      #     OPENAI_KEY: ${{ secrets.OPENAI_KEY }}
      #     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

Note: in MDX content, expressions containing `{{ }}` can be parsed by the renderer. Keep those expressions inside fenced code blocks or inline backticks when used in documentation to avoid parsing issues.

Triggering the workflow and seeing the runner pick up jobs
Commit and push the workflow file to a repository that has been granted access to the runner group. If the self-hosted runner is running and listening, it will receive and execute the job. Example runner log output when a job is picked up:

```text theme={null}
✓ Connected to GitHub
Current runner version: '2.336.0'
2026-08-25 06:15:41Z: Listening for Jobs
2026-08-25 06:19:51Z: Running job: test-composite-action
2026-08-25 06:20:02Z: Job test-composite-action completed with result: Succeeded
```

In the Actions UI you can view job details showing the job ran on runner `prod-linux` in `production-shared-group`. The runner reports its machine name (for example `SilentShadow`), and the logs will list each action executed and the job result.

Summary

* Create a runner group to control access and security for self-hosted runners.
* Register self-hosted runners by downloading the runner package, running `./config.sh`, and starting `./run.sh`.
* Use runner labels (for example `self-hosted`, `prod-ubuntu`) in `runs-on` to target specific machines.
* Restrict repository access to runner groups and avoid enabling public repository access unless strictly necessary.

Links and references

* GitHub Actions runner documentation: [https://docs.github.com/actions/hosting-your-own-runners](https://docs.github.com/actions/hosting-your-own-runners)
* GitHub Enterprise administration: [https://docs.github.com/enterprise-cloud@latest/admin](https://docs.github.com/enterprise-cloud@latest/admin)
* Actions runner releases: [https://github.com/actions/runner/releases](https://github.com/actions/runner/releases)

> [card] [Watch Video](https://learn.kodekloud.com/user/courses/github-administration-certification/module/3ba840c5-7afb-4da9-8395-a430a6354557/lesson/81a342ea-d1e3-49f2-8d04-3e235964f3aa)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.