brandon/oam
1
0
Fork 0
mirror of https://gitea.com/mcereda/oam.git synced 2026-02-09 05:44:23 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
cba9d9193e64fb9e2c4aef864bf19a220dc140c0
oam/knowledge base/gitea.md
Michele Cereda a4423457db chore(gitea): improved code search
2025-08-05 21:31:03 +02:00

8.7 KiB
Raw Blame History

Gitea

  1. TL;DR
  2. Installation
  3. Configuration
    1. LFS
    2. HTTPS
      1. HTTP redirection to HTTPS
    3. Send emails
    4. Use Oauth2 for authentication
      1. Map OAuth2 users to Gitea teams and organizations
    5. Search
  4. Further readings
    1. Sources

TL;DR

Setup 
# Install from source.
git clone 'https://github.com/go-gitea/gitea' -b 'release/v1.22' && cd 'gitea' \
&& TAGS='bindata sqlite sqlite_unlock_notify' make build

# Install as package.
apk add 'gitea'
brew install 'gitea'
emerge -aqv 'gitea'
pacman -S 'gitea'
pkg install 'gitea'

# Kubernetes
helm repo add 'gitea-charts' 'https://dl.gitea.com/charts/'
helm upgrade --install 'gitea' 'gitea-charts/gitea'
Usage 
# Start after installation from source.
./gitea web

Installation

Container image

Compose file example.

The git user has UID and GID set to 1000 by default.
Change those in the compose file or whatever one needs to.

One can optionally define the administrative user during the initial setup.
If no administrative user is defined in that moment, the first registered user becomes the administrator.

Configuration

Refer the Configuration cheat sheet.

Settings are loaded from the configuration file usually found at /etc/gitea/app.ini.

Container users can update the configuration file through environment variables.
The image runs environment-to-ini before running the server, which maps them to values in the ini file:

  • Variables in the form GITEA__{{SECTION_NAME}}__{{KEY_NAME}} are mapped to the [section_name] ini section and the KEY_NAME key with the provided value.
  • Variables in the form GITEA__{{SECTION_NAME}}__{{KEY_NAME}}__{{PATH_TO_FILE}} are mapped to the [section_name] ini section and the KEY_NAME key with the value loaded from the specified file.

Environment variables usually restricted to the 0-9A-Z_ reduced character.
To allow setting up sections with characters outside of that set, characters shall be escaped as a UTF8 byte string. E.g. to configure:

[log.console]
COLORIZE = false
STDERR   = true

One would need to encode . as _0X2E_ and set the environment variables GITEA__LOG_0x2E_CONSOLE__COLORIZE=false and GITEA__LOG_0x2E_CONSOLE__STDERR=false.
Other examples can be found on the configuration cheat sheet.

If using the helm chart with Kubernetes, the configuration settings defined in the values' gitea.config key are saved in the gitea-inline-config secret and are then used to build the configuration file in the container.

LFS

Enable the built-in LFS support:

[server]
LFS_START_SERVER = true

[lfs]
PATH = /home/gitea/data/lfs  # defaults to "{{data_directory}}/lfs"

HTTPS

Refer HTTPS setup to encrypt connections to Gitea.

If the certificate is signed by a third party certificate authority (i.e. not self-signed), then the cert.pem file shall contain the certificate chain too.
The server certificate must be the first entry in cert.pem, followed by the intermediaries in order (if any).
The root certificate does not need to be included, as the connecting client must already have it in order to establish any trust relationship.

The file path in the configuration is relative to the GITEA_CUSTOM environment variable when it is a relative path.

Self-signed certificate

  1. Generate a self signed certificate:

    gitea cert --host 'gitea.company.com'
docker compose exec server gitea cert --host 'gitea.company.com'

  2. Reference the certificate files in the configuration file:

    [server]
PROTOCOL  = https
ROOT_URL  = https://gitea.company.com:3000/
HTTP_PORT = 3000
CERT_FILE = /path/to/cert.pem
KEY_FILE  = /path/to/key.pem
ACME certificate

Defaults to using Let's Encrypt.

[server]
PROTOCOL       = https
DOMAIN         = gitea.company.com
ENABLE_ACME    = true
ACME_ACCEPTTOS = true
ACME_DIRECTORY = https
ACME_EMAIL     = user@company.com  # can be omitted here and provided manually at first run, after which it is cached

HTTP redirection to HTTPS

Gitea's server is able to listen on one port only and requires a separate service to provide redirection.
If HTTPS is enabled and one wants to offer an HTTP port to redirect HTTP requests from, enable the HTTP redirection service:

[server]
REDIRECT_OTHER_PORT = true
PORT_TO_REDIRECT    = 3080  # http port that will be redirected to the https port

When using Docker, make sure this port is published too.

Send emails

Use SMTP servers as relay should one want to leverage accounts at email providers.

AWS 
[mailer]
ENABLED   = true
PROTOCOL  = smtp+starttls
SMTP_ADDR = email-smtp.eu-west-1.amazonaws.com
SMTP_PORT = 587
USER      = AKIA…7890
PASSWD    = `ABCD…7890`
FROM      = noreply@gitea.company.com
Gmail

Gmail will not allow the direct use of one's Google account password.
Create an App password and enable 2FA on one's Google account.

[mailer]
ENABLED   = true
PROTOCOL  = smtps
SMTP_ADDR = smtp.gmail.com
SMTP_PORT = 465
FROM      = user@gmail.com
USER      = user
PASSWD    = `App_Password`

Use Oauth2 for authentication

Remember to set up a mailer, should one want to require email confirmation during registration.

Google Cloud example

  1. Create a Client ID in Google Cloud with at least the following settings:

    Application type: web application
Name: whatever  # anything is fine here
Authorized JavaScript origins:
  - https://gitea.company.com:3000  # the ROOT_URL of one's instance
Authorized redirect URIs:
  - # the 'Google' identifier here needs to be the name given to the provider in the next step
    https://gitea.company.com:3000/user/oauth2/Google/callback

  2. Configure the provider in the Gitea instance at Site Administration > Identity & Access > Authentication Sources with at least the following settings:

    Authentication Type: OAuth2
Authentication Name: Google  # this defines the identifier for the redirect URI above
OAuth2 Provider: Google
Client ID (Key): 012345678901-abcdefghijklmnopqrstuvwxyz012345.apps.googleusercontent.com
Client Secret: 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

  3. Configure the Gitea instance to automatically create users from the provider:

    [oauth2_client]
ENABLE_AUTO_REGISTRATION: true
USERNAME: email

Map OAuth2 users to Gitea teams and organizations

TODO

Search

Users can do repository-level code search by default.

The builtin code search is based on the git grep command. It is fast and efficient for small repositories.
Better code search support could be achieved by setting up the repository indexer.

Refer Repository indexer.

Indexing the repository's contents can consume lots of resources.
This is especially true when an index is created for the first time or globally updated (e.g. after upgrading Gitea).

[mailer]
REPO_INDEXER_ENABLED = true

Further readings

Alternatives:

Sources