Forgejo-runner Installation and Setup Guide08.01.26

# Forgejo Runner Installation and Setup Guide

## Overview

Forgejo is a self-hosted Git service, and the Forgejo runner is a separate binary that allows you to run CI/CD jobs. This guide will help you install and set up the Forgejo runner on your server.

## Prerequisites

- A server with Forgejo installed.
- Access to the command line with root privileges.
- A user account (e.g., `git`) that will run the Forgejo runner.

## Step 1: Create a User

Create a dedicated user for running the Forgejo runner (if not already created). In this example, we will use the user `git`.

```bash
sudo adduser git
```

## Step 2: Download the Forgejo Runner Binary

1. Download the Forgejo runner binary from the official Forgejo releases page.
2. Save the binary to the `/usr/local/bin/` directory.

```bash
sudo mv forgejo-runner /usr/local/bin/
```

3. Change the ownership of the binary to the `git` user:

```bash
sudo chown git:git /usr/local/bin/forgejo-runner
```

## Step 3: Obtain a Global Runner Token

1. Log in to your Forgejo instance as an administrator.
2. Navigate to **Admin** > **Actions** > **Runners**.
3. Generate a Global Runner Token and copy it for later use.

## Step 4: Register the Runner

1. Switch to the `git` user and navigate to its home directory:

```bash
su - git
cd ~
```

2. Execute the following command to register the runner:

```bash
forgejo-runner register
```

3. You will be prompted to enter the following information:

- **Instance**: `http://code.salamander-jewelry.net`
   - **Token**: `clPeCQiBrOuAcnORqHLK6rRagoULlewjyVRv5pgk` (replace with your actual token)
   - **Name**: `dockerx`
   - **Label**: `docker3:docker://node:20-bookworm`

**Note**: Pay special attention to the label format, which is composed of `label:type of app container`.

## Step 5: Create a Runner Configuration File

Generate a configuration file for the runner:

```bash
forgejo-runner generate-config > config.yml
```

## Step 6: Run the Runner

Start the runner in daemon mode:

```bash
forgejo-runner daemon
```

## Step 7: Test the Runner

1. Create a test YAML file for the runner in the `.forgejo/workflows/` directory:

```bash
mkdir -p .forgejo/workflows
nano .forgejo/workflows/demo.yaml
```

2. Add the following content to the `demo.yaml` file:

```yaml
on: [push]
jobs:
  test:
    runs-on: docker3
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Run a test command
        run: echo "Hello from Forgejo Runner!"
```

## Step 8: Register the Runner as a Systemd Service

To ensure the runner starts automatically on boot, create a systemd service file:

1. Create the service file:

```bash
sudo nano /etc/systemd/system/forgejo-runner.service
```

2. Add the following content to the service file:

```ini
[Unit]
Description=Forgejo Runner
Documentation=https://forgejo.org/docs/latest/admin/actions/
After=docker.service

[Service]
ExecStart=/usr/local/bin/forgejo-runner daemon
ExecReload=/bin/kill -s HUP $MAINPID

# This user and working directory must already exist
User=git
WorkingDirectory=/home/git
Restart=on-failure
TimeoutSec=0
RestartSec=10

[Install]
WantedBy=multi-user.target
```

## Step 9: Load the Daemon

Reload the systemd daemon to recognize the new service:

```bash
sudo systemctl daemon-reload
```

## Step 10: Enable the Runner to Start on Boot

Enable the Forgejo runner service to start automatically on system boot:

```bash
sudo systemctl enable forgejo-runner.service
```

## Conclusion

You have successfully installed and set up the Forgejo runner. It should now be running and ready to execute jobs for your Forgejo instance. If you encounter any issues, refer to the Forgejo documentation or check the logs for more information.

---

https://forgejo.org/docs/latest/admin/actions/runner-installation/

Anonymous

Forgejo-runner Installation and Setup Guide08.01.26

Information Epoch 1770532810