Let’s Customize Gitea

Gitea is an awesome and It is lightweight enough to run comfortably on a 512 MB Raspberry Pi. Git service that can be hosted anywhere. It is open source and written in Golang. Many of my own projects are hosted across multiple Gitea instances. A standard Gitea installation will look a bit bare.

We can Check out my template hacks here. many aspects of Gitea by overriding its default templates. This allows us to change the header, footer, and navigation sections with ease. You can also override public resources like images.

To start overriding the templates, create the folder custom in Gitea’s home folder or working directory.

drwxr-xr-x 4 gitea gitea 4096 Mar 29 17:03 custom
drwxr-xr-x 6 gitea gitea 4096 Jan 17 03:40 data
-rw-r--r-- 1 gitea gitea 73   Mar 29 17:29 .gitconfig
srw-rw-rw- 1 gitea gitea 0    Mar 29 17:29 gitea.socket
drwxr-xr-x 3 gitea gitea 4096 Mar 29 15:52 log
drwxr----- 3 gitea gitea 4096 Jan 17 06:44 .pki
drwxr-xr-x 3 gitea gitea 4096 Jan 17 06:44 repos
drwx------ 2 gitea gitea 4096 Jan 17 05:49 .ssh

We will change some elements of the navigation bar and override the favicons. To do this, the custom folder will have the following file structure.

|__ public
|   |__ img
|       |__ favicon.ico
|       |__ favicon.png
|__ templates
    |__ base
        |__ head_navbar.tmpl

The navigation elements are templated by the source file base/head_navbar.tmpl and can be overridden by the path custom/templates/base/head_navbar.tmpl.

Match the template files with your Gitea version using the repository Use the release tag that matches your Gitea version. or you may experience runtime errors.

You can view the The live repository master is used here to demonstrate. override structure of the templates by looking directly at the source files. You must restart the Gitea instance for changes to take effect.

The Customization

Let’s copy base/head_navbar.tmpl to our local path at custom/templates/base/head_navbar.tmpl and replace the brand icon and link.

@@ -1,7 +1,8 @@
<div class="ui container" id="navbar">
  <div class="item brand" style="justify-content: space-between;">
-   <a href="{{AppSubUrl}}/">
-     <img class="ui mini image" src="{{AppSubUrl}}/img/gitea-sm.png">
+   <a title="Head back to https://www.thedroneely.com" href="/">
+     <img style="display: inline; border-radius: 6px;" class="ui mini image" src="/android-chrome-192x192.png">
+     <span style="margin-left: 0.65em;">www.thedroneely.com</span>
  <div class="ui basic icon button mobile-only" id="navbar-expand-toggle">
    <i class="sidebar icon"></i>

Finally let’s disable the help button in the navigation bar by adjusting the template.

@@ -118,7 +119,7 @@
- <a class="item" target="_blank" rel="noopener noreferrer" href="https://docs.gitea.io">{{.i18n.Tr "help"}}</a>
+ <!-- <a class="item" target="_blank" rel="noopener noreferrer" href="https://docs.gitea.io">{{.i18n.Tr "help"}}</a> -->
  <div class="right stackable menu">
    {{if .ShowRegistrationButton}}
      <a class="item{{if .PageIsSignUp}} active{{end}}" href="{{AppSubUrl}}/user/sign_up">

The Ensure that you bypass your browser’s cache to see the changes. can be overridden by placing the files favicon.ico and favicon.png inside custom/public/img.

Caching and Changes

Gitea uses a service worker that caches files Gitea is bloated on the front-end. This means that some changes may not show up immediately. Clear the browser cache (history) or “hard refresh” the Or unregister the service worker. to view the changes.

The Results

This guide did not contain drastic changes to Gitea, however the sky is the limit. You can Note: No longer available. Switched my git front-end to cgit. the results of my changes by visiting this website’s self hosted Git server.

29 March 2019 — Written
2 March 2022 — Updated
Thedro Neely — Creator
lets-customize-gitea.md — Article

More Content


Web Ring



  1. https://thedroneely.com/git/
  2. https://thedroneely.com/
  3. https://thedroneely.com/posts/
  4. https://thedroneely.com/projects/
  5. https://thedroneely.com/about/
  6. https://thedroneely.com/contact/
  7. https://thedroneely.com/abstracts/
  8. https://ko-fi.com/thedroneely
  9. https://thedroneely.com/tags/git/
  10. https://thedroneely.com/tags/webdev/
  11. https://thedroneely.com/posts/lets-customize-gitea/#isso-thread
  12. https://thedroneely.com/posts/rss.xml
  13. https://thedroneely.com/images/lets-customize-gitea.png
  14. https://gitea.io/
  15. https://git-scm.com/
  16. https://go.dev/doc/
  17. https://www.thedroneely.com/git/thedroneely/dotfiles
  18. https://thedroneely.com/images/standard-gitea-instance.png
  19. https://www.thedroneely.com/git/thedroneely/gitea-templates/tree/
  20. https://thedroneely.com/posts/lets-customize-gitea/#code-block-51654bd
  21. https://thedroneely.com/posts/lets-customize-gitea/#code-block-e1ab852
  22. https://github.com/go-gitea/gitea/blob/master/templates/base/head_navbar.tmpl
  23. https://github.com/go-gitea/gitea/tags
  24. https://github.com/go-gitea/gitea/tree/master/templates
  25. https://thedroneely.com/posts/lets-customize-gitea/#the-customization
  26. https://raw.githubusercontent.com/go-gitea/gitea/master/templates/base/head_navbar.tmpl
  27. https://thedroneely.com/posts/lets-customize-gitea/#code-block-e7e8e1c
  28. https://thedroneely.com/posts/lets-customize-gitea/#code-block-226e919
  29. https://thedroneely.com/posts/lets-customize-gitea/#caching-and-changes
  30. https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API
  31. https://thedroneely.com/posts/lets-customize-gitea/#the-results
  32. https://git.zx2c4.com/cgit/about/
  33. https://www.thedroneely.com/git/thedroneely/gitea-templates/
  34. https://www.thedroneely.com/posts/lets-customize-gitea.md
  35. https://thedroneely.com/posts/writing-with-vale/
  36. https://thedroneely.com/posts/improving-paperless-interface/
  37. https://thedroneely.com/posts/cooking-and-baking-linux-distributions-in-nix/
  38. https://git.sr.ht/~sircmpwn/openring
  39. https://drewdevault.com/2022/11/12/In-praise-of-Plan-9.html
  40. https://drewdevault.com/
  41. https://mxb.dev/blog/the-indieweb-for-everyone/
  42. https://mxb.dev/
  43. https://www.taniarascia.com/simplifying-drag-and-drop/
  44. https://www.taniarascia.com/
  45. https://thedroneely.com/posts/lets-customize-gitea#isso-thread
  46. https://thedroneely.com/posts/lets-customize-gitea#code-block-51654bd
  47. https://thedroneely.com/posts/lets-customize-gitea#code-block-e1ab852
  48. https://thedroneely.com/posts/lets-customize-gitea#the-customization
  49. https://thedroneely.com/posts/lets-customize-gitea#code-block-e7e8e1c
  50. https://thedroneely.com/posts/lets-customize-gitea#code-block-226e919
  51. https://thedroneely.com/posts/lets-customize-gitea#caching-and-changes
  52. https://thedroneely.com/posts/lets-customize-gitea#the-results
  53. https://thedroneely.com/posts/writing-nixos-modules-and-switching-to-cgit/
  54. https://thedroneely.com/posts/adding-headroom-with-javascript/
  55. https://thedroneely.com/posts/web-browsers/
  56. https://thedroneely.com/posts/lets-customize-gitea/
  57. https://thedroneely.com/posts/finding-that-one-percent/
  58. https://drewdevault.com/2022/09/16/Open-source-matters.html
  59. https://mxb.dev/blog/make-free-stuff/
  60. https://thedroneely.com/sitemap.xml
  61. https://thedroneely.com/index.json
  62. https://thedroneely.com/resume/
  63. https://gitlab.com/tdro
  64. https://github.com/tdro
  65. https://codeberg.org/tdro
  66. https://thedroneely.com/analytics
  67. https://thedroneely.com/posts/lets-customize-gitea#
  68. https://creativecommons.org/licenses/by-sa/2.0/
  69. https://thedroneely.com/git/thedroneely/thedroneely.com
  70. https://opensource.org/licenses/GPL-3.0
  71. https://www.thedroneely.com/
  72. https://thedroneely.com/posts/lets-customize-gitea/#