|
| 1 | +--- |
| 2 | +date: "2019-04-05T16:00:00+02:00" |
| 3 | +title: "FAQ" |
| 4 | +slug: "faq" |
| 5 | +weight: 5 |
| 6 | +toc: true |
| 7 | +draft: false |
| 8 | +menu: |
| 9 | + sidebar: |
| 10 | + parent: "help" |
| 11 | + name: "FAQ" |
| 12 | + weight: 5 |
| 13 | + identifier: "faq" |
| 14 | +--- |
| 15 | + |
| 16 | +# Frequently Asked Questions |
| 17 | + |
| 18 | +This page contains some common questions and answers. |
| 19 | +Also see [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}) |
| 20 | + |
| 21 | +* [How to migrate from Gogs/GitHub/etc. to Gitea](#how-to-migrate-from-gogs-github-etc-to-gitea) |
| 22 | +* [Where does Gitea store "x" file](#where-does-gitea-store-x-file) |
| 23 | +* [Not seeing a clone URL or the clone URL being incorrect](#not-seeing-a-clone-url-or-the-clone-url-being-incorrect) |
| 24 | +* [Custom Templates not loading or working incorrectly](#custom-templates-not-loading-or-working-incorrectly) |
| 25 | +* [Active user vs login prohibited user](#active-user-vs-login-prohibited-user) |
| 26 | +* [Setting up logging](#setting-up-logging) |
| 27 | +* [What is Swagger?](#what-is-swagger) |
| 28 | +* [Adjusting your server for public/private use](#adjusting-your-server-for-public-private-use) |
| 29 | + * [Preventing spammers](#preventing-spammers) |
| 30 | + * [Only allow/block certain email domains](#only-allow-block-certain-email-domains) |
| 31 | + * [Issue only users](#issue-only-users) |
| 32 | + * [Enable Fail2ban](#enable-fail2ban) |
| 33 | +* [Adding custom themes](#how-to-add-use-custom-themes) |
| 34 | +* [SSHD vs built-in SSH](#sshd-vs-built-in-ssh) |
| 35 | +* [Gitea is running slow](#gitea-is-running-slow) |
| 36 | +* [Can't create repositories/files](#cant-create-repositories-files) |
| 37 | +* [Translation is incorrect/how to add more translations](#translation-is-incorrect-how-to-add-more-translations) |
| 38 | +* [Hooks aren't running](#hooks-aren-t-running) |
| 39 | +* [SSH Issues](#ssh-issues) |
| 40 | + * [SSH Common Errors](#ssh-common-errors) |
| 41 | +* [Missing releases after migration repository with tags](#missing-releases-after-migrating-repository-with-tags) |
| 42 | +* [LFS Issues](#lfs-issues) |
| 43 | + |
| 44 | + |
| 45 | +## How to migrate from Gogs/GitHub/etc. to Gitea |
| 46 | +To migrate from Gogs to Gitea: |
| 47 | + |
| 48 | +* [Gogs version 0.9.146 or less]({{< relref "doc/upgrade/from-gogs.en-us.md" >}}) |
| 49 | +* [Gogs version 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286) |
| 50 | + |
| 51 | +To migrate from GitHub to Gitea, you can use Gitea's [Migrator tool](https://gitea.com/gitea/migrator) |
| 52 | + |
| 53 | +To migrate from Gitlab to Gitea, you can use this non-affiliated tool: |
| 54 | +https://github.com/loganinak/MigrateGitlabToGogs |
| 55 | + |
| 56 | +## Where does Gitea store "x" file |
| 57 | +* WorkPath |
| 58 | + * Environment variable `GITEA_WORK_DIR` |
| 59 | + * Else binary location |
| 60 | +* AppDataPath (default for database, indexers, etc.) |
| 61 | + * `APP_DATA_PATH` from `app.ini` |
| 62 | + * Else `%(WorkPath)/data` |
| 63 | +* CustomPath (custom templates) |
| 64 | + * Environment variable `GITEA_CUSTOM` |
| 65 | + * Else `%(WorkPath)/custom` |
| 66 | +* HomeDir |
| 67 | + * Unix: Environment variable `HOME` |
| 68 | + * Windows: Environment variable `USERPROFILE`, else environment variables `HOMEDRIVE`+`HOMEPATH` |
| 69 | +* RepoRootPath |
| 70 | + * `ROOT` in `app.ini` |
| 71 | + * Else `%(HomeDir)/gitea-repositories` |
| 72 | +* INI (config file) |
| 73 | + * `-c` flag |
| 74 | + * Else `%(CustomPath)/conf/app.ini` |
| 75 | +* SQLite Database |
| 76 | + * `PATH` in `database` section of `app.ini` |
| 77 | + * Else `%(AppDataPath)/gitea.db` |
| 78 | + |
| 79 | +## Not seeing a clone URL or the clone URL being incorrect |
| 80 | +There are a few places that could make this show incorrectly. |
| 81 | + |
| 82 | +1. If using a reverse proxy, make sure you have followed the correction directions in the [reverse proxy guide]({{< relref "doc/usage/reverse-proxies.en-us.md" >}}) |
| 83 | +2. Make sure you have correctly set `ROOT_URL` in the `server` section of your `app.ini` |
| 84 | + |
| 85 | +If certain clone options aren't showing up (HTTP/S or SSH), the following options can be checked in your `app.ini` |
| 86 | + |
| 87 | +`DISABLE_HTTP_GIT`: if set to true, there will be no HTTP/HTTPS link |
| 88 | +`DISABLE_SSH`: if set to true, there will be no SSH link |
| 89 | +`SSH_EXPOSE_ANONYMOUS`: if set to false, SSH links will be hidden for anonymous users |
| 90 | + |
| 91 | + |
| 92 | +## Custom Templates not loading or working incorrectly |
| 93 | +Gitea's custom templates must be added to the correct location or Gitea will not find and use them. |
| 94 | +The correct path for the template(s) will be relative to the `CustomPath` |
| 95 | + |
| 96 | +1. To find `CustomPath`, look for Custom File Root Path in Site Administration -> Configuration |
| 97 | + * If that doesn't exist, you can try `echo $GITEA_CUSTOM` |
| 98 | +2. If you are still unable to find a path, the default can be [calculated above](#where-does-gitea-store-x-file) |
| 99 | +3. Once you have figured out the correct custom path, you can refer to the [customizing Gitea]({{< relref "doc/advanced/customizing-gitea.en-us.md" >}}) page to add your template to the correct location. |
| 100 | + |
| 101 | +## Active user vs login prohibited user |
| 102 | +In Gitea, an "active" user refers to a user that has activated their account via email. |
| 103 | +A "login prohibited" user is a user that is not allowed to log in to Gitea anymore |
| 104 | + |
| 105 | +## Setting up logging |
| 106 | +* [Official Docs]({{< relref "doc/advanced/logging-documentation.en-us.md" >}}) |
| 107 | + |
| 108 | +## What is Swagger? |
| 109 | +[Swagger](https://swagger.io/) is what Gitea uses for its API. |
| 110 | +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` |
| 111 | +For more information, refer to Gitea's [API docs]({{< relref "doc/advanced/api-usage.en-us.md" >}}) |
| 112 | + |
| 113 | +[Swagger Example](https://try.gitea.io/api/swagger) |
| 114 | + |
| 115 | +## Adjusting your server for public/private use |
| 116 | + |
| 117 | +### Preventing spammers |
| 118 | +There are multiple things you can combine to prevent spammers. |
| 119 | + |
| 120 | +1. By only whitelisting certain domains with OpenID (see below) |
| 121 | +2. Setting `ENABLE_CAPTCHA` to `true` in your `app.ini` and properly configuring `RECAPTCHA_SECRET` and `RECAPTCHA_SITEKEY` |
| 122 | +3. Settings `DISABLE_REGISTRATION` to `true` and creating new users via the [CLI]({{< relref "doc/usage/command-line.en-us.md" >}}), [API]({{< relref "doc/advanced/api-usage.en-us.md" >}}), or Gitea's Admin UI |
| 123 | + |
| 124 | +### Only allow/block certain email domains |
| 125 | +If using OpenID, you can configure `WHITELISTED_URIS` or `BLACKLISTED_URIS` in your `app.ini` |
| 126 | +**NOTE:** whitelisted takes precedence, so if it is non-blank then blacklisted is ignored |
| 127 | + |
| 128 | +### Issue only users |
| 129 | +The current way to achieve this is to create/modify a user with a max repo creation limit of 0. |
| 130 | + |
| 131 | +### Enable Fail2ban |
| 132 | + |
| 133 | +Use [Fail2Ban]({{ relref "doc/usage/fail2ban-setup.md" >}}) to monitor and stop automated login attempts or other malicious behavior based on log patterns |
| 134 | + |
| 135 | +## How to add/use custom themes |
| 136 | +Gitea supports two official themes right now, `gitea` and `arc-green` (`light` and `dark` respectively) |
| 137 | +To add your own theme, currently the only way is to provide a complete theme (not just color overrides) |
| 138 | + |
| 139 | +As an example, let's say our theme is `arc-blue` (this is a real theme, and can be found [in this issue](https://github.com/go-gitea/gitea/issues/6011)) |
| 140 | +Name the `.css` file `theme-arc-blue.css` and add it to your custom folder in `custom/pulic/css` |
| 141 | +Allow users to use it by adding `arc-blue` to the list of `THEMES` in your `app.ini` |
| 142 | + |
| 143 | +## SSHD vs built-in SSH |
| 144 | +SSHD is the built-in SSH server on most Unix systems. |
| 145 | +Gitea also provides its own SSH server, for usage when SSHD is not available. |
| 146 | + |
| 147 | +## Gitea is running slow |
| 148 | +The most common culprit for this is loading federated avatars. |
| 149 | +This can be turned off by setting `ENABLE_FEDERATED_AVATAR` to `false` in your `app.ini` |
| 150 | +Another option that may need to be changed is setting `DISABLE_GRAVATAR` to `true` in your `app.ini` |
| 151 | + |
| 152 | +## Can't create repositories/files |
| 153 | +Make sure that Gitea has sufficient permissions to write to its home directory and data directory. |
| 154 | +See [AppDataPath and RepoRootPath](#where-does-gitea-store-x-file) |
| 155 | + |
| 156 | +**Note for Arch users:** At the time of writing this, there is an issue with the Arch package's systemd file including this line: |
| 157 | +`ReadWritePaths=/etc/gitea/app.ini` |
| 158 | +Which makes all other paths non-writeable to Gitea. |
| 159 | + |
| 160 | +## Translation is incorrect/how to add more translations |
| 161 | +Our translations are currently crowd-sourced on our [Crowdin project](https://crowdin.com/project/gitea) |
| 162 | +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. |
| 163 | + |
| 164 | +## Hooks aren't running |
| 165 | +If Gitea is not running hooks, a common cause is incorrect setup of SSH keys. |
| 166 | +See [SSH Issues](#ssh-issues) for more information. |
| 167 | + |
| 168 | +You can also try logging into the administration panel and running the `Resynchronize pre-receive, update and post-receive hooks of all repositories.` option. |
| 169 | + |
| 170 | +## SSH issues |
| 171 | +If you cannot reach repositories over `ssh`, but `https` works fine, consider looking into the following. |
| 172 | + |
| 173 | +First, make sure you can access Gitea via SSH. |
| 174 | + |
| 175 | + |
| 176 | +If the connection is successful, you should receive an error message like the following: |
| 177 | +``` |
| 178 | +Hi there, You've successfully authenticated, but Gitea does not provide shell access. |
| 179 | +If this is unexpected, please log in with password and setup Gitea under another user. |
| 180 | +``` |
| 181 | + |
| 182 | +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. |
| 183 | + |
| 184 | +If you cannot connect at all, your SSH key may not be configured correctly locally. |
| 185 | +This is specific to SSH and not Gitea, so will not be covered here. |
| 186 | + |
| 187 | +### SSH Common Errors |
| 188 | + |
| 189 | +``` |
| 190 | +Permission denied (publickey). |
| 191 | +fatal: Could not read from remote repository. |
| 192 | +``` |
| 193 | + |
| 194 | +This error signifies that the server rejected a log in attempt, check the |
| 195 | +following things: |
| 196 | + |
| 197 | +* On the client: |
| 198 | + * Ensure the public and private ssh keys are added to the correct Gitea user. |
| 199 | + * Make sure there are no issues in the remote url. In particular, ensure the name of the |
| 200 | + git user (before the `@`) is spelled correctly. |
| 201 | + * Ensure public and private ssh keys are correct on client machine. |
| 202 | +* On the server: |
| 203 | + * Make sure the repository exists and is correctly named. |
| 204 | + * Check the permissions of the `.ssh` directory in the system user's home directory. |
| 205 | + * Verify that the correct public keys are added to `.ssh/authorized_keys`. |
| 206 | + Try to run `Rewrite '.ssh/authorized_keys' file (for Gitea SSH keys)` on the |
| 207 | + Gitea admin panel. |
| 208 | + * Read Gitea logs. |
| 209 | + * Read /var/log/auth (or similar). |
| 210 | + * Check permissions of repositories. |
| 211 | + |
| 212 | +The following is an example of a missing public SSH key where authentication |
| 213 | +succeeded, but some other setting is preventing SSH from reaching the correct |
| 214 | +repository. |
| 215 | + |
| 216 | +``` |
| 217 | +fatal: Could not read from remote repository. |
| 218 | +
|
| 219 | +Please make sure you have the correct access rights |
| 220 | +and the repository exists. |
| 221 | +``` |
| 222 | + |
| 223 | +In this case, look into the following settings: |
| 224 | + |
| 225 | +* On the server: |
| 226 | + * Make sure that the `git` system user has a usable shell set |
| 227 | + * Verify this with `getent passwd git | cut -d: -f7` |
| 228 | + * `usermod` or `chsh` can be used to modify this. |
| 229 | + * Ensure that the `gitea serv` command in `.ssh/authorized_keys` uses the |
| 230 | + correct configuration file. |
| 231 | + |
| 232 | +## Missing releases after migrating repository with tags |
| 233 | + |
| 234 | +To migrate an repository *with* all tags, you need to do two things: |
| 235 | + |
| 236 | +* Push tags to the repository: |
| 237 | +``` |
| 238 | + git push --tags |
| 239 | + ``` |
| 240 | + |
| 241 | + * (Re-)sync tags of all repositories within Gitea: |
| 242 | + ``` |
| 243 | + gitea admin repo-sync-releases |
| 244 | + ``` |
| 245 | + |
| 246 | +## LFS Issues |
| 247 | + |
| 248 | +For issues concerning LFS data upload |
| 249 | + |
| 250 | +``` |
| 251 | +batch response: Authentication required: Authorization error: <GITEA_LFS_URL>/info/lfs/objects/batch |
| 252 | +Check that you have proper access to the repository |
| 253 | +error: failed to push some refs to '<GIT_REPO_URL>' |
| 254 | +``` |
| 255 | +Check the value of `LFS_HTTP_AUTH_EXPIRY` in your `app.ini` file. |
| 256 | +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. |
| 257 | + |
| 258 | +You may want to set this value to `60m` or `120m`. |
0 commit comments