Today, I want to theme my forgejo instance.

After leaving GitHub to host my own Forgejo instance, I wanted to customize my Forgejo instance a bit.

Nothing fancy though, I just want to change the primary color of the instance. Sounds easy at first, but it’s actually more complicated than you can imagine, because forgejo lacks support for advanced interface customization, and the documentation for theming is far from clear.

Using themes

Gitea supports themes (Forgejo is a Gitea fork), so we’re going to customize it that way, as I just want to change the color scheme of my instance.

Prerequisites

Before I can customize my instance, I need to make sure I have set the GITEA_CUSTOM environment variable. As you’ve probably seen on my docker-compose.yml file from the migration article, it is already set. We need to make sure it is equal to <your data path>/gitea (in my case /data/gitea), otherwise it will just recreate configuration files in the folder provided by your GITEA_CUSTOM path (so a new forgejo instance basically) and you risk corrupting your database.

Then, I create the folder where Gitea (Forgejo) themes need to be stored. In my case, I just ran the following command into my base forgejo directory (where the docker-compose.yml file is)

mkdir -p ./data/gitea/public/assets/css

Anything in this folder will be served by the Forgejo web server.

Adding a new theme

Now that I’ve configured Forgejo to look up for custom content, I can add the theme.

My theme will be called forgejo-ctrlaltcat as I will be using the colors of my small company Ctrl Alt Cat:

cd ./data/gitea/public/assets/css
touch theme-forgejo-ctrlaltcat.css # The filname for your css file must start with "theme-"

Now that the css file is ready, I need to tell forgejo there is a theme called forgejo-ctrlaltcat, which is possible by editing my gitea config located at data/gitea/conf/app.ini. I need to add an [ui] section as it is not already there for me, add the theme to the list of already existing ones, and change the default theme:

[ui]
THEMES = gitea,arc-green,forgejo-dark,forgejo-light,forgejo-auto,forgejo-ctrlaltcat
DEFAULT_THEME = forgejo-ctrlaltcat

New accounts will have the forgejo-ctrlaltcat theme selected by default.

Changing the theme for already exisiting accounts

Changing your forgejo theme is pretty easy. Click on your avatar, then Settings, then Appearance. Here you’ll be able to select your theme.

Customizing the accent colors

As my theme is empty at the moment, I’ll get the default forgejo theme first in order to not start from scratch, and because I actually enjoy forgejo’s default dark theme.

I did not find another way than manually copying the css content of the default forgejo dark theme available at https://<instance>/assets/css/theme-forgejo-dark.css.

After writing this to my theme css file, I need to actually change the colors, which is possible via the css variables used by the forgejo dark theme.

Here’s my css:

:root {
	--color-primary: oklch(0.6268 0.2325 303.9) !important;
	--color-primary-hover: oklch(0.7 0.1875 303.9) !important;
	--color-primary-active: oklch(0.5706 0.2837 303.9) !important;
	--color-accent: var(--color-primary) !important;
}

I know that forgejo actually uses more color variables than these four, but I was actually too lazy to do every single one of them, and it works fine just by changing those values.