Skip to content

Commit 56c793a

Browse files
msyeamsyea
committed
Fix readme
1 parent a8045fc commit 56c793a

File tree

1 file changed

+137
-12
lines changed

1 file changed

+137
-12
lines changed

‎README.md‎

Lines changed: 137 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,150 @@
11
# GitHub Actions Runner
22

3-
Built on `ubuntu:20.04`, configured for rootless dind 🎉, impossible without valuable advice from @kenichi-shibata and @sidick.
3+
Built on `ubuntu:20.04`, configured for rootless dind 🎉, impossible without valuable advice from @kenichi-shibata and @sidick and work by @myoung34.
44
## Inspiration from
5-
https://github.com/cruizba/ubuntu-dind
6-
https://github.com/myoung34/docker-github-actions-runner
7-
https://github.com/docker-library/docker/tree/master/20.10/dind
5+
* https://github.com/cruizba/ubuntu-dind showed me it was possible on ubuntu
6+
* https://github.com/myoung34/docker-github-actions-runner showed it running docker outside docker - inspired API and wrote some README - rights theirs
7+
* https://github.com/docker-library/docker/tree/master/20.10/dind-rootless for their outstanding work
88

99
# Images
1010
- [msyea/ubuntu-docker](https://hub.docker.com/repository/docker/msyea/ubuntu-docker)
1111
- [msyea/ubuntu-dind](https://hub.docker.com/repository/docker/msyea/ubuntu-dind)
1212
- [msyea/github-actions-runner](https://hub.docker.com/repository/docker/msyea/github-actions-runner)
1313

14+
Docker Github Actions Runner
15+
============================
1416

17+
[![Docker Pulls](https://img.shields.io/docker/pulls/msyea/github-actions-runner.svg)](https://hub.docker.com/r/msyea/github-actions-runner)
18+
19+
This will run the [new self-hosted github actions runners](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/hosting-your-own-runners).
20+
## Environment Variables ##
21+
22+
| Environment Variable | Description |
23+
| --- | --- |
24+
| `RUNNER_NAME` | The name of the runner to use. Supercedes (overrides) `RUNNER_NAME_PREFIX` |
25+
| `RUNNER_NAME_PREFIX` | A prefix for a randomly generated name (followed by a random 13 digit string). You must not also provide `RUNNER_NAME`. Defaults to `github-runner` |
26+
| `ACCESS_TOKEN` | A [github PAT](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) to use to generate `RUNNER_TOKEN` dynamically at container start. Not using this requires a valid `RUNNER_TOKEN` |
27+
| `ORG_RUNNER` | Only valid if using `ACCESS_TOKEN`. This will set the runner to an org runner. Default is 'false'. Valid values are 'true' or 'false'. If this is set to true you must also set `ORG_NAME` and makes `REPO_URL` unneccesary |
28+
| `ORG_NAME` | The organization name for the runner to register under. Requires `ORG_RUNNER` to be 'true'. No default value. |
29+
| `LABELS` | A comma separated string to indicate the labels. Default is 'default' |
30+
| `REPO_URL` | If using a non-organization runner this is the full repository url to register under such as 'https://github.com/myoung34/repo' |
31+
| `RUNNER_TOKEN` | If not using a PAT for `ACCESS_TOKEN` this will be the runner token provided by the Add Runner UI (a manual process). Note: This token is short lived and will change frequently. `ACCESS_TOKEN` is likely preferred. |
32+
| `RUNNER_WORKDIR` | The working directory for the runner. Runners on the same host should not share this directory. Default is '/_work'. This must match the source path for the bind-mounted volume at RUNNER_WORKDIR, in order for container actions to access files. |
33+
| `RUNNER_GROUP` | Name of the runner group to add this runner to (defaults to the default runner group) |
34+
| `GITHUB_HOST` | Optional URL of the Github Enterprise server e.g github.mycompany.com. Defaults to `github.com`. |
35+
36+
## Examples ##
37+
38+
### Note ###
39+
40+
If you're using a RHEL based OS with SELinux, add `--security-opt=label=disable` to prevent [permission denied](https://github.com/myoung34/docker-github-actions-runner/issues/9)
41+
42+
### Manual ###
43+
44+
```shell
45+
# org runner
46+
docker run -d --restart always --name github-runner \
47+
-e RUNNER_NAME_PREFIX="myrunner" \
48+
-e ACCESS_TOKEN="footoken" \
49+
-e RUNNER_WORKDIR="/tmp/github-runner-your-repo" \
50+
-e RUNNER_GROUP="my-group" \
51+
-e ORG_RUNNER="true" \
52+
-e ORG_NAME="octokode" \
53+
-e LABELS="my-label,other-label" \
54+
msyea/github-actions-runner:latest
55+
# per repo
56+
docker run -d --restart always --name github-runner \
57+
-e REPO_URL="https://github.com/myoung34/repo" \
58+
-e RUNNER_NAME="foo-runner" \
59+
-e RUNNER_TOKEN="footoken" \
60+
-e RUNNER_WORKDIR="/tmp/github-runner-your-repo" \
61+
-e RUNNER_GROUP="my-group" \
62+
msyea/github-actions-runner:latest
1563
```
16-
# start container
17-
docker run --privileged -it msyea/github-actions-runner bash
1864

19-
# start dockerd
20-
dockerd-rootless.sh &
65+
Or shell wrapper:
66+
67+
```shell
68+
function github-runner {
69+
name=github-runner-${1//\//-}
70+
org=$(dirname $1)
71+
repo=$(basename $1)
72+
tag=${3:-latest}
73+
docker rm -f $name
74+
docker run -d --restart=always \
75+
-e REPO_URL="https://github.com/${org}/${repo}" \
76+
-e RUNNER_TOKEN="$2" \
77+
-e RUNNER_NAME="linux-${repo}" \
78+
-e RUNNER_WORKDIR="/tmp/github-runner-${repo}" \
79+
-e RUNNER_GROUP="my-group" \
80+
-e LABELS="my-label,other-label" \
81+
--name $name ${org}/github-runner:${tag}
82+
}
83+
84+
github-runner your-account/your-repo AARGHTHISISYOURGHACTIONSTOKEN
85+
github-runner your-account/some-other-repo ARGHANOTHERGITHUBACTIONSTOKEN ubuntu-xenial
86+
```
87+
88+
Or `docker-compose.yml`:
89+
90+
```yml
91+
version: '2.3'
92+
93+
services:
94+
worker:
95+
image: msyea/github-actions-runner:latest
96+
environment:
97+
REPO_URL: https://github.com/example/repo
98+
RUNNER_NAME: example-name
99+
RUNNER_TOKEN: someGithubTokenHere
100+
RUNNER_GROUP: my-group
101+
ORG_RUNNER: 'false'
102+
LABELS: linux,x64,gpu
103+
```
104+
## Usage From GH Actions Workflow ##
105+
106+
```yml
107+
name: Package
108+
109+
on:
110+
release:
111+
types: [created]
112+
113+
jobs:
114+
build:
115+
runs-on: self-hosted
116+
steps:
117+
- uses: actions/checkout@v1
118+
- name: build packages
119+
run: make all
120+
```
121+
122+
## Automatically Acquiring a Runner Token ##
123+
124+
A runner token can be automatically acquired at runtime if `ACCESS_TOKEN` (a GitHub personal access token) is a supplied. This uses the [GitHub Actions API](https://developer.github.com/v3/actions/self_hosted_runners/#create-a-registration-token). e.g.:
125+
126+
```shell
127+
docker run -d --restart always --name github-runner \
128+
-e ACCESS_TOKEN="footoken" \
129+
-e RUNNER_NAME="foo-runner" \
130+
-e RUNNER_WORKDIR="/tmp/github-runner-your-repo" \
131+
-e RUNNER_GROUP="my-group" \
132+
-e ORG_RUNNER="true" \
133+
-e ORG_NAME="octokode" \
134+
-e LABELS="my-label,other-label" \
135+
msyea/github-actions-runner:latest
136+
```
137+
138+
## Create GitHub personal access token ##
139+
140+
Creating GitHub personal access token (PAT) for using by self-hosted runner make sure the following scopes are selected:
141+
142+
* repo (all)
143+
* admin:org (all) **_(mandatory for organization-wide runner)_**
144+
* admin:public_key - read:public_key
145+
* admin:repo_hook - read:repo_hook
146+
* admin:org_hook
147+
* notifications
148+
* workflow
21149

22-
# test
23-
docker ps
24-
docker run hello-world
25-
```
150+
Also, when creating a PAT for self-hosted runner which will process events from several repositories of the particular organization, create the PAT using organization owner account. Otherwise your new PAT will not have sufficient privileges for all repositories.

0 commit comments

Comments
 (0)