date: “2019-04-05T16:00:00+02:00” title: “FAQ” slug: “faq” weight: 5 toc: false draft: false aliases:
This page contains some common questions and answers.
For more help resources, check all Support Options.
Table of Contents
{{< toc >}}
Version 1.20.x will be used for this example.
On our downloads page you will see a 1.20 directory, as well as directories for 1.20.0, 1.20.1.
The 1.20 directory is the nightly build, which is built on each merged commit to the release/v1.20
branch.
The 1.20.0 directory is a release build that was created when the v1.20.0
tag was created.
The nightly builds (1.x) downloads will change as commits are merged to their respective branch, they contain the latest changes/fixes before a tag release is built.
If a bug fix is targeted on 1.20.1 but 1.20.1 is not released yet, you can get the “1.20-nightly” build to get the bug fix.
To migrate from Gogs to Gitea:
To migrate from GitHub to Gitea, you can use Gitea’s built-in migration form.
In order to migrate items such as issues, pull requests, etc. you will need to input at least your username.
To migrate from GitLab to Gitea, you can use this non-affiliated tool:
https://github.com/loganinak/MigrateGitlabToGogs
AppWorkPath
--work-path
flagGITEA_WORK_DIR
%(APP_DATA_PATH)
(default for database, indexers, etc.)
APP_DATA_PATH
from app.ini
AppWorkPath
/data
CustomPath
(custom templates)
--custom-path
flagGITEA_CUSTOM
AppWorkPath
/custom
HOME
USERPROFILE
, else environment variables HOMEDRIVE
+HOMEPATH
ROOT
in the [repository] section of app.ini
if absoluteAppWorkPath
/ROOT
if ROOT
in the [repository] section of app.ini
if relative%(APP_DATA_PATH)/gitea-repositories
--config
flagCustomPath
/conf/app.ini
PATH
in database
section of app.ini
%(APP_DATA_PATH)/gitea.db
There are a few places that could make this show incorrectly.
ROOT_URL
in the server
section of your app.ini
If certain clone options aren’t showing up (HTTP/S or SSH), the following options can be checked in your app.ini
DISABLE_HTTP_GIT
: if set to true, there will be no HTTP/HTTPS linkDISABLE_SSH
: if set to true, there will be no SSH linkSSH_EXPOSE_ANONYMOUS
: if set to false, SSH links will be hidden for anonymous usersThis error occurs when the reverse proxy limits the file upload size.
See the reverse proxy guide for a solution with nginx.
Gitea’s custom templates must be added to the correct location or Gitea will not find and use them.
The correct path for the template(s) will be relative to the CustomPath
To find CustomPath
, look for Custom File Root Path in Site Administration -> Configuration
If that doesn’t exist, you can try echo $GITEA_CUSTOM
If you are still unable to find a path, the default can be calculated above
Once you have figured out the correct custom path, you can refer to the customizing Gitea page to add your template to the correct location.
Gitea doesn’t provide a built-in Pages server. You need a dedicated domain to serve static pages to avoid CSRF security risks.
For simple usage, you can use a reverse proxy to rewrite & serve static contents from Gitea’s raw file URLs.
And there are already available third-party services, like a standalone pages server or a caddy plugin, that can provide the required functionality.
In Gitea, an “active” user refers to a user that has activated their account via email.
A “login prohibited” user is a user that is not allowed to log in to Gitea anymore
Swagger is what Gitea uses for its API documentation.
All Gitea instances have the built-in API and there is no way to disable it completely.
You can, however, disable showing its documentation by setting ENABLE_SWAGGER
to false
in the api
section of your app.ini
.
For more information, refer to Gitea’s API docs.
You can see the latest API (for example) on https://try.gitea.io/api/swagger.
You can also see an example of the swagger.json
file at https://try.gitea.io/swagger.v1.json.
There are multiple things you can combine to prevent spammers.
ENABLE_CAPTCHA
to true
in your app.ini
and properly configuring RECAPTCHA_SECRET
and RECAPTCHA_SITEKEY
DISABLE_REGISTRATION
to true
and creating new users via the CLI, API, or Gitea’s Admin UIYou can configure EMAIL_DOMAIN_WHITELIST
or EMAIL_DOMAIN_BLOCKLIST
in your app.ini under [service]
You can configure WHITELISTED_URIS
or BLACKLISTED_URIS
under [openid]
in your app.ini
NOTE: whitelisted takes precedence, so if it is non-blank then blacklisted is ignored
The current way to achieve this is to create/modify a user with a max repo creation limit of 0.
Restricted users are limited to a subset of the content based on their organization/team memberships and collaborations, ignoring the public flag on organizations/repos etc.__
Example use case: A company runs a Gitea instance that requires login. Most repos are public (accessible/browsable by all co-workers).
At some point, a customer or third party needs access to a specific repo and only that repo. Making such a customer account restricted and granting any needed access using team membership(s) and/or collaboration(s) is a simple way to achieve that without the need to make everything private.
Use Fail2Ban to monitor and stop automated login attempts or other malicious behavior based on log patterns
Gitea supports three official themes right now, gitea
(light), arc-green
(dark), and auto
(automatically switches between the previous two depending on operating system settings).
To add your own theme, currently the only way is to provide a complete theme (not just color overrides)
As an example, let’s say our theme is arc-blue
(this is a real theme, and can be found in this issue)
Name the .css
file theme-arc-blue.css
and add it to your custom folder in custom/public/assets/css
Allow users to use it by adding arc-blue
to the list of THEMES
in your app.ini
SSHD is the built-in SSH server on most Unix systems.
Gitea also provides its own SSH server, for usage when SSHD is not available.
The most common culprit for this is loading federated avatars.
This can be turned off by setting ENABLE_FEDERATED_AVATAR
to false
in your app.ini
Another option that may need to be changed is setting DISABLE_GRAVATAR
to true
in your app.ini
Make sure that Gitea has sufficient permissions to write to its home directory and data directory.
See AppDataPath and RepoRootPath
Note for Arch users: At the time of writing this, there is an issue with the Arch package’s systemd file including this line:
ReadWritePaths=/etc/gitea/app.ini
Which makes all other paths non-writeable to Gitea.
Our translations are currently crowd-sourced on our Crowdin project
Whether you want to change a translation or add a new one, it will need to be there as all translations are overwritten in our CI via the Crowdin integration.
If you can push but can’t see push activities on the home dashboard, or the push doesn’t trigger webhook, there are a few possibilities:
chmod a+x any-script
If you cannot reach repositories over ssh
, but https
works fine, consider looking into the following.
First, make sure you can access Gitea via SSH.
ssh git@myremote.example
If the connection is successful, you should receive an error message like the following:
Hi there, You've successfully authenticated, but Gitea does not provide shell access.
If this is unexpected, please log in with password and setup Gitea under another user.
If you do not get the above message but still connect, it means your SSH key is not being managed by Gitea. This means hooks won’t run, among other potential problems.
If you cannot connect at all, your SSH key may not be configured correctly locally. This is specific to SSH and not Gitea, so will not be covered here.
Permission denied (publickey).
fatal: Could not read from remote repository.
This error signifies that the server rejected a log in attempt, check the following things:
@
) is spelled correctly.On the server:
.ssh
directory in the system user’s home directory..ssh/authorized_keys
.Try to run Rewrite '.ssh/authorized_keys' file (for Gitea SSH keys)
on the
Gitea admin panel.
The following is an example of a missing public SSH key where authentication succeeded, but some other setting is preventing SSH from reaching the correct repository.
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
In this case, look into the following settings:
git
system user has a usable shell setgetent passwd git | cut -d: -f7
usermod
or chsh
can be used to modify this.gitea serv
command in .ssh/authorized_keys
uses the
correct configuration file.To migrate an repository with all tags, you need to do two things:
git push --tags
gitea admin repo-sync-releases
For issues concerning LFS data upload
batch response: Authentication required: Authorization error: <GITEA_LFS_URL>/info/lfs/objects/batch
Check that you have proper access to the repository
error: failed to push some refs to '<GIT_REPO_URL>'
Check the value of LFS_HTTP_AUTH_EXPIRY
in your app.ini
file.
By default, your LFS token will expire after 20 minutes. If you have a slow connection or a large file (or both), it may not finish uploading within the time limit.
You may want to set this value to 60m
or 120m
.
Gitea provides a sub-command gitea migrate
to initialize the database, after which you can use the admin CLI commands to add users like normal.
There is no setting for password resets. It is enabled when a mail service is configured, and disabled otherwise.
As an admin, you can change any user’s password (and optionally force them to change it on next login)…
Site Administration -> User Accounts
page and editing a user.Keep in mind most commands will also need a global flag to point the CLI at the correct configuration.
As a user you can change it…
Settings -> Account
page (this method requires you to know your current password).Forgot Password
link.If the Forgot Password/Account Recovery
page is disabled, please contact your administrator to configure a mail service.
In Gitea version 1.11
we moved to goldmark for markdown rendering, which is CommonMark compliant.
If you have markdown that worked as you expected prior to version 1.11
and after upgrading it’s not working anymore, please look through the CommonMark spec to see whether the problem is due to a bug or non-compliant syntax.
If it is the latter, usually there is a compliant alternative listed in the spec.
If you are receiving errors on upgrade of Gitea using MySQL that read:
ORM engine initialization failed: migrate: do migrate: Error: 1118: Row size too large...
Please run gitea convert
or run ALTER TABLE table_name ROW_FORMAT=dynamic;
for each table in the database.
The underlying problem is that the space allocated for indices by the default row format
is too small. Gitea requires that the ROWFORMAT
for its tables is DYNAMIC
.
If you are receiving an error line containing Error 1071: Specified key was too long; max key length is 1000 bytes...
then you are attempting to run Gitea on tables which use the ISAM engine. While this may have worked by chance in previous versions of Gitea, it has never been officially supported and
you must use InnoDB. You should run ALTER TABLE table_name ENGINE=InnoDB;
for each table in the database.
If you are using MySQL 5, another possible fix is
SET GLOBAL innodb_file_format=Barracuda;
SET GLOBAL innodb_file_per_table=1;
SET GLOBAL innodb_large_prefix=1;
Unfortunately MySQL’s utf8
charset does not completely allow all possible UTF-8 characters, in particular Emoji.
They created a new charset and collation called utf8mb4
that allows for emoji to be stored but tables which use
the utf8
charset, and connections which use the utf8
charset will not use this.
Please run gitea convert
, or run ALTER DATABASE database_name CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
for the database_name and run ALTER TABLE table_name CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
for each table in the database.
Gitea requires the system or browser to have one of the supported Emoji fonts installed, which are Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol, Noto Color Emoji and Twemoji Mozilla. Generally, the operating system should already provide one of these fonts, but especially on Linux, it may be necessary to install them manually.
Before Gitea has read the configuration file and set-up its logging it will log a number of things to stdout in order to help debug things if logging does not work.
You can stop this logging by setting the --quiet
or -q
option. Please note this will only stop logging until Gitea has set-up its own logging.
If you report a bug or issue you MUST give us logs with this information restored.
You should only set this option once you have completely configured everything.
Sometimes when there are migrations the old columns and default values may be left unchanged in the database schema. This may lead to warning such as:
2020/08/02 11:32:29 ...rm/session_schema.go:360:Sync2() [W] Table user Column keep_activity_private db default is , struct default is 0
These can safely be ignored, but you are able to stop these warnings by getting Gitea to recreate these tables using:
gitea doctor recreate-table user
This will cause Gitea to recreate the user table and copy the old data into the new table with the defaults set appropriately.
You can ask Gitea to recreate multiple tables using:
gitea doctor recreate-table table1 table2 ...
And if you would like Gitea to recreate all tables simply call:
gitea doctor recreate-table
It is highly recommended to back-up your database before running these commands.
repository.ROOT
), ensuring they are in the correct layout <REPO_ROOT>/[user]/[repo].git
.
<ROOT_URL>/admin/config
for the repository root path.<ROOT_URL>/admin/repos/unadopted
and search.
ALLOW_ADOPTION_OF_UNADOPTED_REPOSITORIES
.In most cases, it’s caused by broken NFS lock system. You can try to stop Gitea process and
run flock -n /data-nfs/gitea/queues/LOCK echo 'lock acquired'
to see whether the lock can be acquired immediately.
If the lock can’t be acquired, NFS might report some errors like lockd: cannot monitor node-3, statd: server rpc.statd not responding, timed out
in its server logs.
Then the NFS lock could be reset by:
# /etc/init.d/nfs stop
# rm -rf /var/lib/nfs/sm/*
# /etc/init.d/nfs start