Run GitHub Actions on a Synology NAS

April 14th 2023 GitHub Docker Synology

Although GitHub-hosted runners should usually be your first choice for running GitHub Actions, you sometimes still might want to use a self-hosted runner to save on costs or work around IP blocking. If you own a Synology NAS, you can also use it to host a GitHub runner. I found a helpful blog post to get me started, but some things have changed since then, so for future reference I'm documenting how I made it work on a DS218+ running DSM 7.1.1.

Before you decide on this approach, you should consider the security implications. To be on the safe side, you should only use it with private repositories to have full control over the running code.

The runner will be running as a Docker container, so you first need to install the official Docker package. By default, it doesn't allow launching new containers from within a container. To allow it, you need to connect to your Synology via SSH. You can enable SSH in the Control Panel:

Enable SSH in Synology COntrol Panel

You can then connect to it from your computer with the following command:

ssh myusername@mysynology

The Docker folder will usually be /volume1/docker. Inside it, you need to do the following:

  • Create a link to the socket to give containers access to it:

    ln -s /var/run/docker.sock /volume1/docker/docker.sock
  • Create a working directory for the GitHub Actions runner:

    mkdir /volume1/docker/github-runner

The link to the Docker socket doesn't persist across reboots. You can create a triggered task to recreate it at reboot. To do that, navigate to Task Scheduler in Control Panel. There, create a new triggered task:

Create a triggered task in Synology COntrol Panel

On the General tab, give it a name and select Boot-up as the Event. On the Task Settings tab, input the following as the Run command:

mkdir /volume1/docker/github-runner

Now you're ready to configure the Docker GitHub Actions Runner container. I decided to use a docker-compose.yml file for this. I started with the file from the documentation and modified it to my needs (i.e., to add the runner to my organization):

version: "2.3"
    image: myoung34/github-runner:latest
      ORG_NAME: yourOrgName
      ACCESS_TOKEN: someGithubTokenHere
      RUNNER_WORKDIR: /tmp/github-runner
      RUNNER_SCOPE: "org"
      - "/volume1/docker/docker.sock:/var/run/docker.sock"
      - "/volume1/docker/github-runner:/volume1/docker/github-runner"
      # note: a quirk of docker-in-docker is that this path
      # needs to be the same path on host and inside the container,
      # docker mgmt cmds run outside of docker but expect the paths from within

Of course, change yourOrgName to your actual GitHub organization name. And replace someGithubTokenHere with your personal access token. You can create one in GitHub settings. Make sure to select all the required scopes. You can find all supported environment variables documented here.

Copy the file to a folder on your Synology and via your SSH connection run the following command in that folder to start the container:

sudo docker-compose up -d

You should now see the container running in your Synology's Docker UI:

GitHub runner container in Synology Docker UI

It should laso be in the list of runners for your GitHub organization. You can navigate to it from your organization page: Settings > Actions > Runners:

Self-hosted runner in GitHub organization settings

This means that your self-hosted GitHub Actions runner is ready. To use it for a workflow, set it as its runner:

runs-on: self-hosted

By following the instructions in this post, you can set up a self-hosted GitHub Actions runner for your GitHub organization on your Synology NAS and use it to run workflows from any repository in that organization. To mitigate security risks, you should only use it for private repositories.

Get notified when a new blog post is published (usually every Friday):

If you're looking for online one-on-one mentorship on a related topic, you can find me on Codementor.
If you need a team of experienced software engineers to help you with a project, contact us at Razum.
Creative Commons License