In the world of continuous integration and continuous deployment (CI/CD), automation is key. GitHub Actions provides a powerful platform to automate workflows directly from your repositories. While GitHub’s hosted runners are a convenient option, there are times when you might need more control over your environment. This is where self-hosted runners come into play. In this blog, we’ll walk you through the process of creating and managing a GitHub self-hosted runner.

Prerequisites

  • An EC2 instance or any running server

    • Set Up Server

    Now we need to set up the server. I am using an EC2 instance for this. You can use any server you have. First, SSH into the server and run the following commands.

    1
    2
    3
    sudo apt-get update

    sudo apt-get upgrade -y

    Create a repository

    For this tutorial, I am going installing the runners at the repository level. You can also install them at the organization level. First, create a new repository or use an existing one. In here I am using a new repository called github-self-hosted-runner

    Now, let’s configure the runner in your specific repository.

  • Go to your GitHub repository
  • Click on Settings
  • In the left sidebar, select Actions > Runners
  • Click the New self-hosted runner button
  • Choose your operating system and follow the instructions provided. You will see a series of commands tailored for your repository

    • Configure Server

    On your server, execute the commands provided by GitHub. Here’s a generalized version:

  • Download the latest runner version

    • 1
    2
    3
    4
    5
    mkdir actions-runner && cd actions-runner

    curl -o actions-runner-linux-x64-2.283.1.tar.gz -L https://github.com/actions/runner/releases/download/v2.283.1/actions-runner-linux-x64-2.283.1.tar.gz

    tar xzf ./actions-runner-linux-x64-2.283.1.tar.gz
  • Configure the runner

    • 1
    ./config.sh --url https://github.com/yourusername/yourrepository --token YOUR_PERSONAL_ACCESS_TOKEN

    Replace https://github.com/yourusername/yourrepository with the URL of your GitHub repository and YOUR_PERSONAL_ACCESS_TOKEN with your personal action token.

    During the configuration process, you will be prompted to enter details such as:

    • Runner Group: You can add the runner to the default group or you can create a new group as well.
    • Runner Name: Provide a unique name for your runner. This helps you identify the runner within GitHub.
    • Runner Work Folder: Specify a directory where the runner will store job-related data. You can use the default location or specify a custom path.

    Examples: 

    1
    2
    3
    Enter the runner group: [Press Enter for default] 
    Enter the name of the runner: [Press Enter for default] <your-runner-name>
    Enter the runner work folder: [Press Enter for default]

    Note: It is recommanded to add new labels because all the self hosted runners will have those default labels but in order to bifurgate the jobs you must need to add new labels. For this tutorial I gave demorunner label to my runner.

  • Run the self-hosted runner

    • 1
    ./run.sh

    Verify the Runner

    Once you complete all the steps you can see your runner on UI but it seems our runner is in the offline state. It’s because it is not running any jobs.

    Start the runner

    If you need to start the runner manually, you can run the run.sh script and it will listen for the jobs. If you need to install the runner as the service you can run svc.sh script. To run the runner as a service, you can use the following command.

    1. Stop the current runner process (if it’s running):

      1
      ./svc.sh stop
    2. Install the runner as a service:

      1
      ./svc.sh install
    3. Start the runner service:

      1
      ./svc.sh start
    4. Check the status of the runner service:

      1
      ./svc.sh status
    5. Enable the service to start on boot:

      1
      sudo systemctl enable actions.runner.<repository_name>.<runner_name>.service

    Using Runner in Workflows

    Now you can use this runner in your workflows. You can specify the runner in your workflow file. Here is an example of how you can use the runner in your workflow file.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    name: CI
    on: [push, pull_request]
    jobs:
      build:
        runs-on: <your runner name>
        steps:
          - name: Checkout code
            uses: actions/checkout@v2
          - name: Run a one-line script
            run: echo Hello, world!

    Check logs

    You can check the logs of the runner by running the following command.

    1
    2
    3
    4
    5
    cd _diag/

    ll

    tail -f <runner-name>-runner-<date>.log

    Conclusion

    In this article, we learned how to create a Self-Hosted GitHub Action Runner. You can find the all the related commands for this tutorial from here. If you have any issue regarding this tutorial, mention your issue in the comment section or reach me through my E-mail.

    Happy Coding