After following this guide, you'll have a simple GitHub action workflow on a GitHub repository of your choice. When new commits are made to your repository, the workflow delegates work to a server which runs in a Docker container.
This guide distinguishes between the client and the server; the client is your own machine; the server is whichever machine will run the tests. This document describes the case where the server is a Docker container running on your own machine.
For guides on how to configure other features in addition to just the runner, go here.
- Install Docker: https://docs.docker.com/engine/install/
- Follow post-installation steps https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user to manage docker as a non-root user
Refence: https://docs.docker.com/docker-for-windows/#test-your-installation
-
Open a terminal window
-
Run
docker --version
to ensure that you have a supported version of Docker:
> docker --version
Docker version 19.03.11-ce, build 42e35e61f3
- Pull the hello-world image from Docker Hub and run a container:
> docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
0e03bdcc26d7: Pull complete
Digest: sha256:d58e752213a51785838f9eed2b7a498ffa1cb3aa7f946dda11af39286c3db9a9
Status: Downloaded newer image for hello-world:latest
Hello from Docker!
This message shows that your installation appears to be working correctly.
...
- List the hello-world image that was downloaded from Docker Hub:
> docker image ls
REPOSITORY TAG IMAGE ID CREATED SIZE
hello-world latest bf756fb1ae65 6 months ago 13.3kB
- List the hello-world container (that exited after displaying “Hello from Docker!”):
> docker container ls --all
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
1d624a063f22 hello-world "/hello" About a minute ago Exited (0) About a minute ago flamboyant_ramanujan
Now we are ready to build our Docker image. The following command will use Dockerfile to build the image. It will create a system user, install necessary system packages and dependencies for the runner.
docker build \
--tag github-actions-runner \
.
The Docker image will create a user called tester
with a password password
. If you want to change the default username and the password, you will need to adjust <username>
and <user password>
for the user which will be added to the Docker image.
docker build \
--tag github-actions-runner \
--build-arg DOCKER_USER="<username>" \
--build-arg DOCKER_PASS="<user password>" \
.
We're almost ready to use our Docker image to set up a GitHub Runner, but first we need to generate an OAuth token, as follows:
-
Go to https://github.com/settings/tokens and click the
Generate new token
button. -
Provide your GitHub password when prompted
-
Fill in a description for the token, for example GitHub runner for github.com/<your organization>/<your repository>
-
Enable the
repo
scope and all of its checkboxes, like so: -
Click
Generate
at the bottom. Make sure to copy its value because we'll need it in the next step
The command below will start the Docker container in daemon mode. The Docker container will run in the background and the terminal will be available. To stop the running container you need to run the stop
command, which is explained in the Cleanup section.
docker run -d --restart always --name github-actions-runner \
--env PERSONAL_ACCESS_TOKEN=<Github OAuth token> \
--env RUNNER_NAME=<runner name to appear on Github> \
--env RUNNER_WORKDIR=/tmp/actions-runner-repo \
--env GITHUB_ORG=<organization or username> \
--env GITHUB_REPO=<name of the repository> \
github-actions-runner:latest
If you stop the running container, the Github actions runner will also stop.
To stop the running Docker container:
docker container stop github-actions-runner
To start the Docker container again:
docker container start github-actions-runner
The command below will run the docker image and set up the runner. When user presses CTRL+C
, it automatically removes the runner from GitHub and removes the Docker container as well.
docker run --rm --name github-actions-runner \
--env PERSONAL_ACCESS_TOKEN=<personal access token> \
--env RUNNER_NAME=<runner name to appear on Github> \
--env RUNNER_WORKDIR=/tmp/actions-runner-repo \
--env GITHUB_ORG=<organization or username> \
--env GITHUB_REPO=<name of the repository> \
github-actions-runner:latest
Warning: If you use --rm
argument, Docker will remove the container and you will loose your changes. However, this can be useful for testing purposes.
If you now go to GitHub https://github.com/<your organization>/<your repository>/settings/actions, you should see a self-hosted runner with status "Idle":
Add the following simple workflow as .github/workflows/self_hosted_ci.yml
in your repository:
name: Self-hosted CI example
on: [push, pull_request]
jobs:
test:
name: test
runs-on: self-hosted
steps:
- name: Show directory listing
shell: bash -l {0}
run: |
ls -la
Now try making a change to one of the files in your repository to see if you can trigger running the simple workflow on your self-hosted server. If successful, the status will change to "Active" while the workflow is running. You can get an overview of previous GitHub actions by navigating to https://github.com/<your organization>/<your repository>/actions.
To stop the running Docker container:
docker container stop github-actions-runner
To start the running Docker container:
docker container start github-actions-runner
To remove a Docker container
docker container rm github-actions-runner
To remove a Docker image
docker image rm github-actions-runner
Use docker inspect
to display details of the container
> docker inspect github-actions-runner
[
{
"Id": "4ff7f37a894e351dc1def53c76959ac30c09083347ada25fcb55dc6687f8d295",
"Created": "2020-07-02T18:29:53.106234584Z",
"Path": "/bin/sh",
...
You can use the command below to only find out the IP address of the container
> docker inspect --format '{{ .NetworkSettings.IPAddress }}' github-actions-runner
172.17.0.2
If you need access to a shell on the running Docker container:
docker exec -ti github-actions-runner /bin/bash
Find instructions for provisioning additional functionality here.