|
2 | 2 |
|
3 | 3 | This sample project demonstrates how to customize a GitHub Actions self-hosted runners with preset environment variables. |
4 | 4 |
|
5 | | -## Environment Variable Customization |
6 | | - |
7 | | -This runner is configured to automatically set the following environment variable before each job runs: |
8 | | - |
9 | | -- `FOO=bar` |
10 | | - |
11 | | -The customization is implemented using GitHub Actions pre-job hooks: |
12 | | - |
13 | | -1. **Script**: `.github/runner/hooks/job-started.sh` - Sets the `FOO=bar` environment variable |
14 | | -2. **Hook**: `ACTIONS_RUNNER_HOOK_JOB_STARTED` - Triggers the script before each job |
15 | | - |
16 | | -([docs](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/run-scripts)) |
17 | | - |
18 | 5 | ## How it works |
19 | 6 |
|
20 | | -When the runner starts, the `ACTIONS_RUNNER_HOOK_JOB_STARTED` is set to `/home/runner/hooks/job-started.sh`. This script is automatically executed by GitHub Actions at the start of each job. The script makes the `FOO=bar` environment variable available to all workflow steps. |
21 | | - |
22 | | -The hook script then sets an environment variable for the job using the `$GITHUB_ENV` file, making it available to all job steps. |
| 7 | +TODO |
23 | 8 |
|
24 | | -## Building the self-hosted runner image |
| 9 | +## Setting up in an existing runner |
25 | 10 |
|
26 | | -This repository includes a Dockerfile under `.github/runner` for building a customized GitHub Actions runner image. The following build args are required: |
27 | | - |
28 | | -- VERSION |
29 | | -- OS |
30 | | -- ARCH |
31 | | -- PACKAGE_CHECKSUM (optional, but recommended) |
| 11 | +1. Copy the `runner-hooks/` directory from this repository to the runner |
| 12 | +2. Create a `.env` file next to your `run.sh` with content: |
32 | 13 |
|
33 | 14 | ```sh |
34 | | -# Build the image with the example defaults used previously in the Dockerfile |
35 | | -docker build \ |
36 | | - --build-arg OS=linux \ |
37 | | - --build-arg ARCH=arm64 \ |
38 | | - --build-arg VERSION=2.328.0 \ |
39 | | - --build-arg PACKAGE_CHECKSUM=b801b9809c4d9301932bccadf57ca13533073b2aa9fa9b8e625a8db905b5d8eb \ |
40 | | - --tag gha-runner:linux-arm64-2.328.0 \ |
41 | | - .github/self-hosted-runner |
| 15 | +ACTIONS_RUNNER_HOOK_JOB_STARTED=<path-to-runner-hooks>/job-started.sh |
42 | 16 | ``` |
43 | 17 |
|
44 | | -## Obtaining a runner registration token |
45 | 18 |
|
46 | | -1. Go to https://github.com/<your-repository>/settings/actions/runners |
47 | | -2. Click "Add new self-hosted runner" |
48 | | -3. Choose your target OS and architecture |
49 | | -4. Copy the token from the `config.sh` step to use when starting the runner |
| 19 | +## Trying with your own machine as a runner |
50 | 20 |
|
51 | | -## Starting the runner |
| 21 | +1. Fork this repository |
| 22 | +2. Access the repository Settings > Actions > Runners |
| 23 | +3. Click "Add new self-hosted runner" |
| 24 | +4. Select your OS and CPU architecture |
| 25 | +5. Run the page's steps but create the following `.env` file next to `run.sh` |
52 | 26 |
|
53 | 27 | ```sh |
54 | | -docker run --rm -it \ |
55 | | - -e RUNNER_TOKEN=<your-token> \ |
56 | | - -e RUNNER_URL=<your-repository> \ |
57 | | - gha-runner:linux-arm64-2.328.0 |
| 28 | +ACTIONS_RUNNER_HOOK_JOB_STARTED=<path-to-this-repository>/runner-hooks/job-started.sh |
58 | 29 | ``` |
| 30 | + |
| 31 | +6. Run `run.sh` to listen for jobs |
| 32 | +7. On GitHub, start the example workflow, which declares `uses: self-hosted` |
0 commit comments