Running Workflow on Self Hosted Runner

Leverage a self-hosted runner to execute your GitHub Actions workflows on your own infrastructure. This guide walks you through verifying the runner in the GitHub UI, starting it on the VM, creating a test workflow, targeting the self-hosted runner, dispatching the job, and reviewing the results.

1. Verify Your Self-Hosted Runner in GitHub

1. In your repository, navigate to Settings > Actions > Runners.
2. Confirm the runner (e.g., prod-ubuntu-runner) appears in an idle state with its labels listed.

2. Start the Runner Process

On the VM hosting your runner, launch the runner service:

cd ~/actions-runner
sudo ./run.sh

You should see:

Current runner version: '2.310.2'
2023-10-24 14:51:44Z: Listening for Jobs

3. Inspect Available Workflows

Because this runner is scoped to the current repository, only workflows in .github/workflows are dispatched here. Check the YAML files:

4. Define a Simple Test Workflow

Create .github/workflows/example.yaml:

name: Test Self-Hosted Runner
on:
  workflow_dispatch:

jobs:
  test-job:
    runs-on: ubuntu-latest
    steps:
      - name: Echo and Sleep
        run: |
          echo "Runner check: OK"
          sleep 15s

Commit this to the default branch to verify it runs on GitHub-hosted runners first.

5. Target Your Self-Hosted Runner

Update runs-on to use all labels from the Runners settings (e.g., self-hosted, linux, prod):

name: Test Self-Hosted Runner
on:
  workflow_dispatch:

jobs:
  test-job:
    runs-on: [self-hosted, linux, prod]
    steps:
      - name: Echo and Sleep
        run: |
          echo "Self-hosted runner: OK"
          sleep 15s

All labels must match exactly.

Commit your changes directly to the main branch:

6. Dispatch the Workflow Manually

1. Go to the Actions tab.
2. Select Test Self-Hosted Runner.
3. Click Run workflow and choose the branch.

The job enters the self-hosted queue, then starts:

7. Review Logs and Runner Output

Once the run completes:

• In GitHub, click the run to see Setup job details, including:
  • Runner name (prod-ubuntu-runner)
  • Runner group (default)
  • Host machine name (ubuntu-host)
• On the VM, the runner console confirms success:

root@ubuntu-host ~/actions-runner ➜ ./run.sh
Job test-job completed with result: Succeeded

8. Key Takeaways

• Always list all runner labels in runs-on.
• Jobs with mismatched labels remain pending.
• Multiple jobs can run in parallel if matching runners are available.

Links and References

• GitHub Actions Runners documentation
• Workflow syntax for GitHub Actions
• GitHub Actions Overview