entitybtw / forgejo-actions-guide.txt

============================================================ STEP-BY-STEP GUIDE: REGISTER & CONFIGURE FORGEJO RUNNER ============================================================ This guide walks you through the entire process: obtaining a registration token, registering the runner, generating a configuration file, and launching the runner with Docker Compose. All placeholders are clearly marked so you can replace them with your own values. ---------------------------------------------------------------- STEP 1: OBTAIN A REGISTRATION TOKEN FROM FORGEJO ---------------------------------------------------------------- 1. Open your Forgejo instance in a browser (e.g., http://YOUR_FORGEJO_URL). 2. Log in as an administrator. 3. Navigate to: Site Administration → Actions → Runners. 4. Click the "Create Runner" button. 5. Copy the generated token. It will look like a long alphanumeric string. Example placeholder: YOUR_REGISTRATION_TOKEN ---------------------------------------------------------------- STEP 2: REGISTER THE RUNNER (CREATE .runner FILE) ---------------------------------------------------------------- Create a working directory and register the runner using the Docker image. mkdir -p ~/forgejo-runner cd ~/forgejo-runner mkdir -p data cache Run the registration command, replacing the placeholders: docker run -it --rm \ -v $(pwd)/data:/data \ -w /data \ --user root \ data.forgejo.org/forgejo/runner:4.0.0 \ forgejo-runner register \ --no-interactive \ --token YOUR_REGISTRATION_TOKEN \ --name YOUR_RUNNER_NAME \ --instance http://YOUR_FORGEJO_URL \ --labels YOUR_LABEL Placeholder explanations: YOUR_REGISTRATION_TOKEN – the token you copied from Forgejo YOUR_RUNNER_NAME – a name you choose (e.g., "websites") YOUR_FORGEJO_URL – the URL of your Forgejo instance (e.g., "192.168.2.76:3000") YOUR_LABEL – one or more labels (e.g., "websites" or "ubuntu-latest,self-hosted") After success, a file data/.runner is created. This stores the runner's permanent credentials. Verify: ls -la data/.runner ---------------------------------------------------------------- STEP 3: GENERATE AND CONFIGURE config.yaml ---------------------------------------------------------------- If you don't already have a config.yaml, generate the default one: docker run --rm \ -v $(pwd)/data:/data \ -w /data \ data.forgejo.org/forgejo/runner:4.0.0 \ forgejo-runner generate-config > data/config.yaml Now open data/config.yaml and customize it. Below is a complete example based on a typical setup. Replace all placeholders (marked with YOUR_*) with your actual values. ---------------------------------------------------------------- EXAMPLE config.yaml (customizable) ---------------------------------------------------------------- # --------------------------- REQUIRED --------------------------- # The URL of your Forgejo instance instance: http://YOUR_FORGEJO_URL # The runner token (can be the registration token or the token from .runner) token: "YOUR_RUNNER_TOKEN" # --------------------------- LOGGING --------------------------- log: level: info # options: trace, debug, info, warn, error, fatal # --------------------------- RUNNER SETTINGS --------------------------- runner: file: .runner # path to registration file (relative to /data) capacity: 1 # number of concurrent tasks timeout: 30m # max job duration (customize as needed) shutdown_timeout: 30m # graceful shutdown timeout insecure: true # set to true if using HTTP (skip TLS verification) fetch_timeout: 30s fetch_interval: 60s report_interval: 10s # Labels determine which jobs this runner picks up. # Format: "label:executor". Executor can be "host" (run on host) or "docker://image". # The label(s) must match the `runs-on` value in your workflows. labels: - "YOUR_LABEL:host" # e.g., "websites:host" # --------------------------- CACHE --------------------------- cache: enabled: true dir: "" # leave empty to use default $HOME/.cache/actcache # --------------------------- CONTAINER EXECUTOR OPTIONS ---------------- container: # Set privileged to true if your workflows need Docker-in-Docker. # If you use a separate docker-in-docker service, you can keep it false. privileged: false # Allow mounting any volume (useful for host directories) valid_volumes: - '**' docker_host: "" # auto-detect; you can override with environment variable DOCKER_HOST force_pull: false # --------------------------- HOST EXECUTOR OPTIONS -------------------- host: workdir_parent: "" # parent directory for job workspaces (default ~/.cache/act/) --- Save the file. The most important fields to adjust are: - instance - token (or remove after registration) - runner.labels (must match your workflow's `runs-on`) - container.privileged (set to true if you run docker commands inside jobs) ---------------------------------------------------------------- STEP 4: CREATE DOCKER-COMPOSE.YML ---------------------------------------------------------------- Create a docker-compose.yml file in the same directory (~/forgejo-runner) with the following content. Replace YOUR_LABEL and any host paths. --- version: '3.8' services: docker-in-docker: image: docker:dind container_name: docker_dind privileged: true command: ['dockerd', '-H', 'tcp://0.0.0.0:2375', '--tls=false'] restart: unless-stopped runner: image: data.forgejo.org/forgejo/runner:4.0.0 container_name: runner depends_on: docker-in-docker: condition: service_started environment: DOCKER_HOST: tcp://docker-in-docker:2375 user: 0:0 # run as root to avoid permission issues volumes: - ./data:/data # config and .runner - ./cache:/cache # optional cache directory # Mount any host directories your workflows need to access: # - /host/path:/container/path # Example mounts (uncomment and adjust): # - /var/www/YOUR_PROJECT:/var/www/YOUR_PROJECT # - /home/user/shared:/shared restart: unless-stopped command: /bin/sh -c " apk update && apk add --no-cache nodejs npm && sleep 5 && forgejo-runner daemon --config /data/config.yaml " --- Note: The command installs Node.js and npm – required for actions like actions/checkout. If you prefer a custom image with Node.js pre-installed, you can build one, but this method works fine. ---------------------------------------------------------------- STEP 5: START THE RUNNER ---------------------------------------------------------------- Launch all services in detached mode: docker compose up -d Check the logs to confirm everything is running: docker compose logs -f runner Expected output: "runner: YOUR_RUNNER_NAME, with version: v4.0.0, with labels: [YOUR_LABEL], declared successfully" "[poller 0] launched" If you see errors, review the logs and verify your config. ---------------------------------------------------------------- STEP 6: TEST WITH A SAMPLE WORKFLOW ---------------------------------------------------------------- Create a test workflow in any repository on your Forgejo instance. Place the file at: .forgejo/workflows/test.yml --- on: [push] jobs: test: runs-on: YOUR_LABEL # must match the label you registered steps: - name: Hello run: echo "Runner is alive!" - name: Check Node.js run: node --version - name: Check Docker run: docker info --- Commit and push the file. The runner should pick up the job automatically. Watch the logs to see the job progress: docker compose logs -f runner ---------------------------------------------------------------- TROUBLESHOOTING COMMON ISSUES ---------------------------------------------------------------- | Symptom | Solution | |------------------------------------|--------------------------------------------------------------------------| | "permission denied" on .runner | Use --user root in registration or set user: 0:0 in docker-compose. | | "cannot find node" | Ensure Node.js is installed (the command above adds it). | | Runner stays idle | Check that the label in your workflow exactly matches the runner's label.| | "invalid token" | Generate a new token in Forgejo admin and re-register. | | Docker errors in jobs | Verify DOCKER_HOST=tcp://docker-in-docker:2375 is set. | ---------------------------------------------------------------- QUICK REFERENCE – PLACEHOLDERS USED IN THIS GUIDE ---------------------------------------------------------------- | Placeholder | Description | |----------------------------|---------------------------------------------------------------------------| | YOUR_FORGEJO_URL | The IP/hostname and port of your Forgejo instance (e.g., 192.168.2.76:3000) | | YOUR_REGISTRATION_TOKEN | The one-time token from Forgejo admin → Actions → Runners → Create Runner | | YOUR_RUNNER_NAME | A friendly name for the runner (appears in admin UI) | | YOUR_LABEL | Label used in workflows (e.g., "websites" or "ubuntu-latest") | | YOUR_RUNNER_TOKEN | The permanent token (usually the same as registration, or taken from .runner) | ---------------------------------------------------------------- END OF GUIDE ----------------------------------------------------------------