Need help with docker-github-runner?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

tcardonne
220 Stars 85 Forks MIT License 31 Commits 17 Opened issues

Description

Run GitHub Actions on self-hosted runner using Docker.

Services available

!
?

Need anything else?

Contributors list

# 208,340
PHP
Symfony
symfony...
Shell
17 commits
# 86,257
dyndns
HTML
nginx
google-...
5 commits
# 14,497
angular...
curl
Git
man-pag...
2 commits
# 427,249
Java
Shell
1 commit
# 184,157
Swift
Go
slack
Heroku
1 commit
# 104,222
Groovy
Visual ...
music-l...
Jenkins
1 commit
# 532,328
confere...
Shell
1 commit

GitHub Runner

Docker Pulls


GitHub allows developers to run GitHub Actions workflows on your own runners. This Docker image allows you to create your own runners on Docker.

For now, there are only Debian Buster (tagged with

latest
and
vX.Y.Z
) and Ubuntu Focal (tagged with
ubuntu-20.04
and
vX.Y.Z-ubuntu-20.04
) images, but I may add more variants in the future. Feel free to create an issue if you want another base image.

Important notes

  • GitHub recommends that you do NOT use self-hosted runners with public repositories, for security reasons.
  • Organization level self-hosted runners are supported (see environment variables), but be advised that the GitHub API for organization level runners is still in public beta and subject to changes.

Usage

Basic usage

Use the following command to start listening for jobs:

shell
docker run -it --name my-runner \
    -e RUNNER_NAME=my-runner \
    -e GITHUB_ACCESS_TOKEN=token \
    -e RUNNER_REPOSITORY_URL=https://github.com/... \
    tcardonne/github-runner

Using Docker inside your Actions

If you want to use Docker inside your runner (ie, build images in a workflow), you can enable Docker siblings by binding the host Docker daemon socket. Please keep in mind that doing this gives your actions full control on the Docker daemon.

docker run -it --name my-runner \
    -e RUNNER_NAME=my-runner \
    -e GITHUB_ACCESS_TOKEN=token \
    -e RUNNER_REPOSITORY_URL=https://github.com/... \
    -v /var/run/docker.sock:/var/run/docker.sock \
    tcardonne/github-runner

Using docker-compose.yml

In

docker-compose.yml
: ```yaml version: "3.7"

services: runner: image: tcardonne/github-runner:latest environment: RUNNERNAME: "my-runner" RUNNERREPOSITORYURL: ${RUNNERREPOSITORYURL} #RUNNERORGANIZATIONURL: ${RUNNERORGANIZATIONURL} GITHUBACCESSTOKEN: ${GITHUBACCESS_TOKEN} volumes: - /var/run/docker.sock:/var/run/docker.sock ```

You can create a

.env
to provide environment variables when using docker-compose : ``` RUNNERREPOSITORYURL=https://github.com/yoururl/yourrepo

or RUNNERORGANIZATIONURL=https://github.com/your-organization

GITHUBACCESSTOKEN=therunnertoken ```

Environment variables

The following environment variables allows you to control the configuration parameters.

| Name | Description | Required/Default value | |------|---------------|-------------| | RUNNERREPOSITORYURL | The runner will be linked to this repository URL | Required if

RUNNER_ORGANIZATION_URL
is not provided | | RUNNERORGANIZATIONURL | The runner will be linked to this organization URL. (Self-hosted runners API for organizations is currently in public beta and subject to changes) | Required if
RUNNER_REPOSITORY_URL
is not provided | | GITHUBACCESSTOKEN | Personal Access Token. Used to dynamically fetch a new runner token (recommended, see below). | Required if
RUNNER_TOKEN
is not provided. | RUNNERTOKEN | Runner token provided by GitHub in the Actions page. These tokens are valid for a short period. | Required if `GITHUBACCESSTOKEN` is not provided | RUNNERWORKDIRECTORY | Runner's work directory | `"work"
| RUNNER_NAME | Name of the runner displayed in the GitHub UI | Hostname of the container
| RUNNER_LABELS | Extra labels in addition to the default: 'self-hosted,Linux,X64' (based on your OS and architecture) |
""
| RUNNER_REPLACE_EXISTING |
"true"
will replace existing runner with the same name,
"false"
will use a random name if there is conflict |
"true"`

Runner Token

In order to link your runner to your repository/organization, you need to provide a token. There is two way of passing the token :

  • via
    GITHUB_ACCESS_TOKEN
    (recommended), containing a Personnal Access Token. This token will be used to dynamically fetch a new runner token, as runner tokens are valid for a short period of time.
    • For a single-repository runner, your PAT should have
      repo
      scopes.
    • For an organization runner, your PAT should have
      admin:org
      scopes.
  • via
    RUNNER_TOKEN
    . This token is displayed in the Actions settings page of your organization/repository, when opening the "Add Runner" page.

Runner auto-update behavior

The GitHub runner (the binary) will update itself when receiving a job, if a new release is available. In order to allow the runner to exit and restart by itself, the binary is started by a supervisord process.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.