Hacking on Gitea
Table of Contents
You should install go and set up your go environment correctly.
Note: When executing make tasks that require external tools, like
make misspell-check, Gitea will automatically download and build these as
necessary. To be able to use these you must have the
on the executable path. If you don’t add the go bin directory to the
executable path you will have to manage this yourself.
Note 2: Go version 1.16
or higher is required; however, it is important
to note that our continuous integration will check that the formatting of the
source code is not changed by
make fmt-check. Unfortunately,
the results of
gofmt can differ by the version of
go. It is therefore
recommended to install the version of Go that our continuous integration is
running. As of last update, it should be Go version 1.17
Gitea makes heavy use of Make to automate tasks and improve development. This guide covers how to install Make.
Install with the package manager.
sudo apt-get install make
sudo yum install make
One of these three distributions of Make will run on Windows:
- Single binary build. Copy somewhere and add to
- MinGW includes a build.
- The binary is called
make.exe. Add the
- The binary is called
- Chocolatey package. Run
choco install make
Note: If you are attempting to build using make with Windows Command Prompt, you may run into issues. The above prompts (git bash, or mingw) are recommended, however if you only have command prompt (or potentially powershell) you can set environment variables using the set command, e.g.
Downloading and cloning the Gitea source code
The recommended method of obtaining the source code is by using
git clone https://github.com/go-gitea/gitea
(Since the advent of go modules, it is no longer necessary to build go projects
from within the
$GOPATH, hence the
go get approach is no longer recommended.)
Download the main Gitea source code as above. Then, fork the Gitea repository on GitHub, and either switch the git remote origin for your fork or add your fork as another remote:
# Rename original Gitea origin to upstream git remote rename origin upstream git remote add origin "firstname.lastname@example.org:$GITHUB_USERNAME/gitea.git" git fetch --all --prune
# Add new remote for our fork git remote add "$FORK_NAME" "email@example.com:$GITHUB_USERNAME/gitea.git" git fetch --all --prune
To be able to create pull requests, the forked repository should be added as a remote to the Gitea sources. Otherwise, changes can’t be pushed.
Building Gitea (Basic)
Take a look at our instructions for building from source.
The simplest recommended way to build from source is:
TAGS="bindata sqlite sqlite_unlock_notify" make build
build target will execute both
backend sub-targets. If the
bindata tag is present, the frontend files will be compiled into the binary. It is recommended to leave out the tag when doing frontend development so that changes will be reflected.
make help for all available
make targets. Also see
.drone.yml to see how our continuous integration works.
To run and continuously rebuild when source files change:
# for both frontend and backend make watch # or: watch frontend files (html/js/css) only make watch-frontend # or: watch backend files (go) only make watch-backend
On macOS, watching all backend source files may hit the default open files limit which can be increased via
ulimit -n 12288 for the current shell or in your shell startup file for all future shells.
Formatting, code analysis and spell check
Our continuous integration will reject PRs that are not properly formatted, fail code analysis or spell check.
You should format your code with
go fmt using:
and can test whether your changes would match the results with:
make fmt-check # which runs make fmt internally
Note: The results of
go fmt are dependent on the version of
You should run the same version of go that is on the continuous integration
server as mentioned above.
make fmt-check will only check if your
format differently - this may be different from the CI server version.
You should run revive, vet and spell-check on the code with:
make revive vet misspell-check
Working on JS and CSS
Frontend development should follow Guidelines for Frontend Development
To build with frontend resources, either use the
watch-frontend target mentioned above or just build once:
make build && ./gitea
Before committing, make sure the linters pass:
Note: When working on frontend code, set
app.ini to prevent undesirable caching of frontend assets.
Building and adding SVGs
SVG icons are built using the
make svg target which compiles the icon sources defined in
build/generate-svg.js into the output directory
public/img/svg. Custom icons can be added in the
Building the Logo
The PNG and SVG versions of the Gitea logo are built from a single SVG source file
assets/logo.svg using the
TAGS="gitea" make generate-images target. To run it, Node.js and npm must be available.
The same process can also be used to generate custom logo PNGs from a SVG source file by updating
assets/logo.svg and running
make generate-images. Omitting the
gitea tag will update only the user-designated logo files.
Updating the API
When creating new API routes or modifying existing API routes, you MUST update and/or create Swagger documentation for these using go-swagger comments. The structure of these comments is described in the specification. If you want more information about the Swagger structure, you can look at the Swagger 2.0 Documentation or compare with a previous PR adding a new API endpoint, e.g. PR #5483
You should be careful not to break the API for downstream users which depend on a stable API. In general, this means additions are acceptable, but deletions or fundamental changes to the API will be rejected.
Once you have created or changed an API endpoint, please regenerate the Swagger documentation using:
You should validate your generated Swagger file and spell-check it with:
make swagger-validate misspell-check
You should commit the changed swagger JSON file. The continuous integration server will check that this has been done using:
Note: Please note you should use the Swagger 2.0 documentation, not the OpenAPI 3 documentation.
Creating new configuration options
When creating new configuration options, it is not enough to add them to the
modules/setting files. You should add information to
and to the
configuration cheat sheet
Changing the logo
When changing the Gitea logo SVG, you will need to run and commit the results of:
This will create the necessary Gitea favicon and others.
If you make breaking changes to any of the database persisted structs in the
models/ directory, you will need to make a new migration. These can be found
models/migrations/. You can ensure that your migrations work for the main
database types using:
make test-sqlite-migration # with sqlite switched for the appropriate database
There are two types of test run by Gitea: Unit tests and Integration Tests.
TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests
Unit tests will not and cannot completely test Gitea alone. Therefore, we have written integration tests; however, these are database dependent.
TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite
will run the integration tests in an sqlite environment. Integration tests
git lfs to be installed. Other database tests are available but
may need adjustment to the local environment.
for more information and how to run a single test.
Our continuous integration will test the code passes its unit tests and that all supported databases will pass integration test in a Docker environment. Migration from several recent versions of Gitea will also be tested.
Please submit your PR with additional tests and integration tests as appropriate.
Documentation for the website
Documentation for the website is found in
docs/. If you change this you
can test your changes to ensure that they pass continuous integration using:
# from the docs directory within Gitea make trans-copy clean build
You will require a copy of Hugo to run this task. Please note: this may generate a number of untracked git objects, which will need to be cleaned up.
Visual Studio Code
tasks.json are provided within
Visual Studio Code. Look at
for more information.
Run Application arrow on the function
func main() in
can quickly start a debuggable Gitea instance.
Output Directory in
Run/Debug Configuration MUST be set to the
gitea project directory (which contains
otherwise, the started instance’s working directory is a GoLand’s temporary directory
and prevents Gitea from loading dynamic resources (eg: templates) in a development environment.
To run unit tests with SQLite in GoLand, set
Go tool arguments of
Once you’re happy with your changes, push them up and open a pull request. It is recommended that you allow Gitea Managers and Owners to modify your PR branches as we will need to update it to main before merging and/or may be able to help fix issues directly.
Any PR requires two approvals from the Gitea maintainers and needs to pass the
continuous integration. Take a look at our
If you need more help pop on to Discord #Develop and chat there.
That’s it! You are ready to hack on Gitea.