Like 0
Fork 0

Last active 1 month ago

forgejo actions guide!

entitybtw revised this gist 1 month ago. Go to revision

No changes

entitybtw revised this gist 1 month ago. Go to revision

1 file changed, 253 insertions

forgejo-actions-guide.txt(file created)

@@ -0,0 +1,253 @@
1 + ============================================================
2 + STEP-BY-STEP GUIDE: REGISTER & CONFIGURE FORGEJO RUNNER
3 + ============================================================
4 +
5 + This guide walks you through the entire process: obtaining a registration
6 + token, registering the runner, generating a configuration file, and
7 + launching the runner with Docker Compose. All placeholders are clearly
8 + marked so you can replace them with your own values.
9 +
10 + ----------------------------------------------------------------
11 + STEP 1: OBTAIN A REGISTRATION TOKEN FROM FORGEJO
12 + ----------------------------------------------------------------
13 +
14 + 1. Open your Forgejo instance in a browser (e.g., http://YOUR_FORGEJO_URL).
15 + 2. Log in as an administrator.
16 + 3. Navigate to: Site Administration → Actions → Runners.
17 + 4. Click the "Create Runner" button.
18 + 5. Copy the generated token. It will look like a long alphanumeric string.
19 +
20 + Example placeholder: YOUR_REGISTRATION_TOKEN
21 +
22 + ----------------------------------------------------------------
23 + STEP 2: REGISTER THE RUNNER (CREATE .runner FILE)
24 + ----------------------------------------------------------------
25 +
26 + Create a working directory and register the runner using the Docker image.
27 +
28 + mkdir -p ~/forgejo-runner
29 + cd ~/forgejo-runner
30 +
31 + mkdir -p data cache
32 +
33 + Run the registration command, replacing the placeholders:
34 +
35 + docker run -it --rm \
36 + -v $(pwd)/data:/data \
37 + -w /data \
38 + --user root \
39 + data.forgejo.org/forgejo/runner:4.0.0 \
40 + forgejo-runner register \
41 + --no-interactive \
42 + --token YOUR_REGISTRATION_TOKEN \
43 + --name YOUR_RUNNER_NAME \
44 + --instance http://YOUR_FORGEJO_URL \
45 + --labels YOUR_LABEL
46 +
47 + Placeholder explanations:
48 + YOUR_REGISTRATION_TOKEN – the token you copied from Forgejo
49 + YOUR_RUNNER_NAME – a name you choose (e.g., "websites")
50 + YOUR_FORGEJO_URL – the URL of your Forgejo instance (e.g., "192.168.2.76:3000")
51 + YOUR_LABEL – one or more labels (e.g., "websites" or "ubuntu-latest,self-hosted")
52 +
53 + After success, a file data/.runner is created. This stores the runner's
54 + permanent credentials.
55 +
56 + Verify:
57 + ls -la data/.runner
58 +
59 + ----------------------------------------------------------------
60 + STEP 3: GENERATE AND CONFIGURE config.yaml
61 + ----------------------------------------------------------------
62 +
63 + If you don't already have a config.yaml, generate the default one:
64 +
65 + docker run --rm \
66 + -v $(pwd)/data:/data \
67 + -w /data \
68 + data.forgejo.org/forgejo/runner:4.0.0 \
69 + forgejo-runner generate-config > data/config.yaml
70 +
71 + Now open data/config.yaml and customize it. Below is a complete example
72 + based on a typical setup. Replace all placeholders (marked with YOUR_*)
73 + with your actual values.
74 +
75 + ----------------------------------------------------------------
76 + EXAMPLE config.yaml (customizable)
77 + ----------------------------------------------------------------
78 +
79 + # --------------------------- REQUIRED ---------------------------
80 + # The URL of your Forgejo instance
81 + instance: http://YOUR_FORGEJO_URL
82 +
83 + # The runner token (can be the registration token or the token from .runner)
84 + token: "YOUR_RUNNER_TOKEN"
85 +
86 + # --------------------------- LOGGING ---------------------------
87 + log:
88 + level: info # options: trace, debug, info, warn, error, fatal
89 +
90 + # --------------------------- RUNNER SETTINGS ---------------------------
91 + runner:
92 + file: .runner # path to registration file (relative to /data)
93 + capacity: 1 # number of concurrent tasks
94 + timeout: 30m # max job duration (customize as needed)
95 + shutdown_timeout: 30m # graceful shutdown timeout
96 + insecure: true # set to true if using HTTP (skip TLS verification)
97 + fetch_timeout: 30s
98 + fetch_interval: 60s
99 + report_interval: 10s
100 +
101 + # Labels determine which jobs this runner picks up.
102 + # Format: "label:executor". Executor can be "host" (run on host) or "docker://image".
103 + # The label(s) must match the `runs-on` value in your workflows.
104 + labels:
105 + - "YOUR_LABEL:host" # e.g., "websites:host"
106 +
107 + # --------------------------- CACHE ---------------------------
108 + cache:
109 + enabled: true
110 + dir: "" # leave empty to use default $HOME/.cache/actcache
111 +
112 + # --------------------------- CONTAINER EXECUTOR OPTIONS ----------------
113 + container:
114 + # Set privileged to true if your workflows need Docker-in-Docker.
115 + # If you use a separate docker-in-docker service, you can keep it false.
116 + privileged: false
117 + # Allow mounting any volume (useful for host directories)
118 + valid_volumes:
119 + - '**'
120 + docker_host: "" # auto-detect; you can override with environment variable DOCKER_HOST
121 + force_pull: false
122 +
123 + # --------------------------- HOST EXECUTOR OPTIONS --------------------
124 + host:
125 + workdir_parent: "" # parent directory for job workspaces (default ~/.cache/act/)
126 +
127 + ---
128 +
129 + Save the file. The most important fields to adjust are:
130 + - instance
131 + - token (or remove after registration)
132 + - runner.labels (must match your workflow's `runs-on`)
133 + - container.privileged (set to true if you run docker commands inside jobs)
134 +
135 + ----------------------------------------------------------------
136 + STEP 4: CREATE DOCKER-COMPOSE.YML
137 + ----------------------------------------------------------------
138 +
139 + Create a docker-compose.yml file in the same directory (~/forgejo-runner)
140 + with the following content. Replace YOUR_LABEL and any host paths.
141 +
142 + ---
143 + version: '3.8'
144 +
145 + services:
146 + docker-in-docker:
147 + image: docker:dind
148 + container_name: docker_dind
149 + privileged: true
150 + command: ['dockerd', '-H', 'tcp://0.0.0.0:2375', '--tls=false']
151 + restart: unless-stopped
152 +
153 + runner:
154 + image: data.forgejo.org/forgejo/runner:4.0.0
155 + container_name: runner
156 + depends_on:
157 + docker-in-docker:
158 + condition: service_started
159 + environment:
160 + DOCKER_HOST: tcp://docker-in-docker:2375
161 + user: 0:0 # run as root to avoid permission issues
162 + volumes:
163 + - ./data:/data # config and .runner
164 + - ./cache:/cache # optional cache directory
165 + # Mount any host directories your workflows need to access:
166 + # - /host/path:/container/path
167 + # Example mounts (uncomment and adjust):
168 + # - /var/www/YOUR_PROJECT:/var/www/YOUR_PROJECT
169 + # - /home/user/shared:/shared
170 + restart: unless-stopped
171 + command: /bin/sh -c "
172 + apk update && apk add --no-cache nodejs npm &&
173 + sleep 5 &&
174 + forgejo-runner daemon --config /data/config.yaml
175 + "
176 + ---
177 +
178 + Note: The command installs Node.js and npm – required for actions like
179 + actions/checkout. If you prefer a custom image with Node.js pre-installed,
180 + you can build one, but this method works fine.
181 +
182 + ----------------------------------------------------------------
183 + STEP 5: START THE RUNNER
184 + ----------------------------------------------------------------
185 +
186 + Launch all services in detached mode:
187 +
188 + docker compose up -d
189 +
190 + Check the logs to confirm everything is running:
191 +
192 + docker compose logs -f runner
193 +
194 + Expected output:
195 + "runner: YOUR_RUNNER_NAME, with version: v4.0.0, with labels: [YOUR_LABEL], declared successfully"
196 + "[poller 0] launched"
197 +
198 + If you see errors, review the logs and verify your config.
199 +
200 + ----------------------------------------------------------------
201 + STEP 6: TEST WITH A SAMPLE WORKFLOW
202 + ----------------------------------------------------------------
203 +
204 + Create a test workflow in any repository on your Forgejo instance.
205 + Place the file at: .forgejo/workflows/test.yml
206 +
207 + ---
208 + on: [push]
209 + jobs:
210 + test:
211 + runs-on: YOUR_LABEL # must match the label you registered
212 + steps:
213 + - name: Hello
214 + run: echo "Runner is alive!"
215 + - name: Check Node.js
216 + run: node --version
217 + - name: Check Docker
218 + run: docker info
219 + ---
220 +
221 + Commit and push the file. The runner should pick up the job automatically.
222 +
223 + Watch the logs to see the job progress:
224 +
225 + docker compose logs -f runner
226 +
227 + ----------------------------------------------------------------
228 + TROUBLESHOOTING COMMON ISSUES
229 + ----------------------------------------------------------------
230 +
231 + | Symptom | Solution |
232 + |------------------------------------|--------------------------------------------------------------------------|
233 + | "permission denied" on .runner | Use --user root in registration or set user: 0:0 in docker-compose. |
234 + | "cannot find node" | Ensure Node.js is installed (the command above adds it). |
235 + | Runner stays idle | Check that the label in your workflow exactly matches the runner's label.|
236 + | "invalid token" | Generate a new token in Forgejo admin and re-register. |
237 + | Docker errors in jobs | Verify DOCKER_HOST=tcp://docker-in-docker:2375 is set. |
238 +
239 + ----------------------------------------------------------------
240 + QUICK REFERENCE – PLACEHOLDERS USED IN THIS GUIDE
241 + ----------------------------------------------------------------
242 +
243 + | Placeholder | Description |
244 + |----------------------------|---------------------------------------------------------------------------|
245 + | YOUR_FORGEJO_URL | The IP/hostname and port of your Forgejo instance (e.g., 192.168.2.76:3000) |
246 + | YOUR_REGISTRATION_TOKEN | The one-time token from Forgejo admin → Actions → Runners → Create Runner |
247 + | YOUR_RUNNER_NAME | A friendly name for the runner (appears in admin UI) |
248 + | YOUR_LABEL | Label used in workflows (e.g., "websites" or "ubuntu-latest") |
249 + | YOUR_RUNNER_TOKEN | The permanent token (usually the same as registration, or taken from .runner) |
250 +
251 + ----------------------------------------------------------------
252 + END OF GUIDE
253 + ----------------------------------------------------------------
Newer Older

Powered by Opengist ⋅ Load: 7227ms⋅

English