date: “2019-04-05T16:00:00+02:00” title: “FAQ” slug: “faq” weight: 5 toc: true draft: false menu: sidebar:
parent: "help"
name: "FAQ"
weight: 5
identifier: "faq"
This page contains some common questions and answers.
Also see Support Options
Version 1.7.x will be used for this example.
NOTE: this example applies to Docker images as well!
On our downloads page you will see a 1.7 directory, as well as directories for 1.7.0, 1.7.1, 1.7.2, 1.7.3, 1.7.4, 1.7.5, and 1.7.6.
The 1.7 and 1.7.0 directories are not the same. The 1.7 directory is built on each merged commit to the release/v1.7
branch.
The 1.7.0 directory, however, is a build that was created when the v1.7.0
tag was created.
This means that 1.x downloads will change as commits are merged to their respective branch (think of it as a separate “master” branch for each release).
On the other hand, 1.x.x downloads should never change.
To migrate from Gogs to Gitea:
To migrate from GitHub to Gitea, you can use Gitea’s Migrator tool
To migrate from Gitlab to Gitea, you can use this non-affiliated tool:
https://github.com/loganinak/MigrateGitlabToGogs
GITEA_WORK_DIR
APP_DATA_PATH
from app.ini
%(WorkPath)/data
GITEA_CUSTOM
%(WorkPath)/custom
HOME
USERPROFILE
, else environment variables HOMEDRIVE
+HOMEPATH
ROOT
in app.ini
%(HomeDir)/gitea-repositories
-c
flag%(CustomPath)/conf/app.ini
PATH
in database
section of app.ini
%(AppDataPath)/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 link
DISABLE_SSH
: if set to true, there will be no SSH link
SSH_EXPOSE_ANONYMOUS
: if set to false, SSH links will be hidden for anonymous users
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
CustomPath
, look for Custom File Root Path in Site Administration -> Configuration
echo $GITEA_CUSTOM
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.
All Gitea instances have the built-in API, though it can be disabled by setting ENABLE_SWAGGER
to false
in the api
section of your app.ini
For more information, refer to Gitea’s API docs
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
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.
Use Fail2Ban to monitor and stop automated login attempts or other malicious behavior based on log patterns
Gitea supports two official themes right now, gitea
and arc-green
(light
and dark
respectively)
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/pulic/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 Gitea is not running hooks, a common cause is incorrect setup of SSH keys.
See SSH Issues for more information.
You can also try logging into the administration panel and running the Resynchronize pre-receive, update and post-receive hooks of all repositories.
option.
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..ssh
directory in the system user’s home directory..ssh/authorized_keys
.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:
Push tags to the repository:
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
.