View source for Forgejo

{{Infobox application
| name = Forgejo
| type = Free and open-source software forge
| image = Forgejo_logo.svg
| website = https://forgejo.org/
| documentation = https://forgejo.org/docs/latest/
| bugTracker = https://codeberg.org/forgejo/forgejo/issues
| platform = Cross-platform
| initialRelease = 15 December 2022
| latestRelease = 11.0.7; 26 October 2025
| programmingLanguage = Go, JavaScript
}}

[https://forgejo.org/ Forgejo] is a lightweight [[wikipedia:Software_forge|software forge]], with a highlight on being completely free software. It's a fork of [[Gitea]].

This article extends the documentation in the [https://nixos.org/manual/nixos/stable/#module-forgejo NixOS manual].

== Usage ==
NixOS provides a module for easily setting-up a Forgejo server, here is an example of typical usage with some optional features:

* Use Nginx to enable easy https configuration
* You can choose what database you want to use (postgres in this example)
* Support for [https://git-lfs.com/ git-lfs]
* Disabling registrations for personal servers
* Support for Actions, similar to Github Actions
* Support for sending email notifications
* No exposed secrets in the nix store, see [[Comparison of secret managing schemes]] and choose one
<syntaxhighlight lang="nixos">
{ lib, pkgs, config, ... }:
let
  cfg = config.services.forgejo;
  srv = cfg.settings.server;
in
{
  services.nginx = {
    virtualHosts.${cfg.settings.server.DOMAIN} = {
      forceSSL = true;
      enableACME = true;
      extraConfig = ''
        client_max_body_size 512M;
      '';
      locations."/".proxyPass = "http://localhost:${toString srv.HTTP_PORT}";
    };
  };

  services.forgejo = {
    enable = true;
    database.type = "postgres";
    # Enable support for Git Large File Storage
    lfs.enable = true;
    settings = {
      server = {
        DOMAIN = "git.example.com";
        # You need to specify this to remove the port from URLs in the web UI.
        ROOT_URL = "https://${srv.DOMAIN}/"; 
        HTTP_PORT = 3000;
      };
      # You can temporarily allow registration to create an admin user.
      service.DISABLE_REGISTRATION = true; 
      # Add support for actions, based on act: https://github.com/nektos/act
      actions = {
        ENABLED = true;
        DEFAULT_ACTIONS_URL = "github";
      };
      # Sending emails is completely optional
      # You can send a test email from the web UI at:
      # Profile Picture > Site Administration > Configuration >  Mailer Configuration 
      mailer = {
        ENABLED = true;
        SMTP_ADDR = "mail.example.com";
        FROM = "noreply@${srv.DOMAIN}";
        USER = "noreply@${srv.DOMAIN}";
      };
    };
    secrets = {
      mailer.PASSWD = config.age.secrets.forgejo-mailer-password.path;
    };
  };

  age.secrets.forgejo-mailer-password = {
    file = ../secrets/forgejo-mailer-password.age;
    mode = "400";
    owner = "forgejo";
  };
}
</syntaxhighlight>

== Actions Runner ==
According to the [https://forgejo.org/docs/latest/admin/actions/#forgejo-runner documentation] the <code>Forgejo runner</code> is:<blockquote>A daemon that fetches workflows to run from a Forgejo instance, executes them, sends back with the logs and ultimately reports its success or failure.</blockquote>In order to use Actions, you will need to setup at least one Runner. You can use your server, another machine or both as runners.
To register a runners you will need to generate a token. https://forgejo.org/docs/latest/user/actions/#forgejo-runner

You can create a server-wide Runner by going to ''Profile Picture > Site Administration > Actions > Runners > Create new Runner.''
Store your token in your [[Comparison of secret managing schemes|secrets management system]] of choice, then add the following to the configuration of the machine to be used as a runner:<syntaxhighlight lang="nixos">
{ pkgs, config, ... }: {
  services.gitea-actions-runner = {
    package = pkgs.forgejo-runner;
    instances.default = {
      enable = true;
      name = "monolith";
      url = "https://git.example.com";
      # Obtaining the path to the runner token file may differ
      # tokenFile should be in format TOKEN=<secret>, since it's EnvironmentFile for systemd
      tokenFile = config.age.secrets.forgejo-runner-token.path;
      labels = [
        "ubuntu-latest:docker://node:16-bullseye"
        "ubuntu-22.04:docker://node:16-bullseye"
        "ubuntu-20.04:docker://node:16-bullseye"
        "ubuntu-18.04:docker://node:16-buster"     
        ## optionally provide native execution on the host:
        # "native:host"
      ];
    };
  };
}
</syntaxhighlight>

== Ensure users ==
Using the following snippet, you can declaratively ensure these users will always exist:
<syntaxhighlight lang="nixos">
sops.secrets.forgejo-admin-password.owner = "forgejo";
systemd.services.forgejo.preStart = let 
  adminCmd = "${lib.getExe cfg.package} admin user";
  pwd = config.sops.secrets.forgejo-admin-password;
  user = "joe"; # Note, Forgejo doesn't allow creation of an account named "admin"
in ''
  ${adminCmd} create --admin --email "root@localhost" --username ${user} --password "$(tr -d '\n' < ${pwd.path})" || true
  ## uncomment this line to change an admin user which was already created
  # ${adminCmd} change-password --username ${user} --password "$(tr -d '\n' < ${pwd.path})" || true
''; 

</syntaxhighlight>
You may remove the <code>--admin</code> flag to create only a regular user. The <code>|| true</code> is necessary, so the snippet does not fail if the user already exists. 

Naturally, instead of sops, you may use any file or secret manager, as explained above.

== Adding a custom theme to Forgejo ==
Its possible to [https://forgejo.org/docs/latest/contributor/customization/ customize the CSS styles and HTML templates of Forgejo] declaratively using Nix. In this simple example i will show you how to: Create a basic theme, set it as the default theme and modify the home template.
{{File|3={ config, pkgs, lib, ... }: { 
  ...
  systemd.tmpfiles.rules = [
    "d '${config.services.forgejo.customDir}/templates' - forgejo forgejo - -"
    "d '${config.services.forgejo.customDir}/public' - forgejo forgejo - -"
    "d '${config.services.forgejo.customDir}/public/assets' - forgejo forgejo - -"
    "d '${config.services.forgejo.customDir}/public/assets/css' - forgejo forgejo - -"
    "C+ '${config.services.forgejo.customDir}/public/assets/css/theme-custom.css' - forgejo forgejo - ${
      ./theme-custom.css
    }"
    "C+ '${config.services.forgejo.customDir}/templates/home.tmpl' - forgejo forgejo - ${
      ./home.tmpl
    }"
  ];

  forgejo.settings.ui = {
    DEFAULT_THEME = "custom";
    THEMES = "forgejo-auto,forgejo-light,forgejo-dark,custom";
  };
  ...
}|name=/etc/nixos/forgejo/default.nix|lang=nix}}{{File|3=@import url('https://fonts.googleapis.com/css2?family=Space+Mono&display=swap');
@import "./theme-forgejo-auto.css";

:root {
    --fonts-override: "Space Mono";
}|name=/etc/nixos/forgejo/theme-custom.css|lang=css}}{{File|3={{template "base/head" .}}
<div role="main" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home"}}{{end}}" class="page-content home">
	<div class="tw-mb-8 tw-px-8">
		<div class="center">
			<div class="hero">
				<h1 class="ui icon header title">
					Forgejo hosted on NixOS!
				</h1>
			</div>
		</div>
	</div>
</div>
{{template "base/footer" .}}|name=/etc/nixos/forgejo/home.tmpl|lang=gotmpl}}
[[Category:Web Applications]]
[[Category:Server]]
[[Category:NixOS Manual]]