¶ O que é Gitea
O Gitea é um sistema de controle de versões fácil de usar. Ele oferece uma interface limpa e intuitiva que facilita a colaboração e o gerenciamento de projetos de código.
É semelhante ao GitHub, Bitbucket e GitLab.
O Gitea Actions oferece suporte compatível com o GitHub Actions.
Histórico:
Primeiro nasceu o projeto Gogs (https://gogs.io/), uma ferramenta open-source de gerenciamento de código-fonte.
Depois veio o Gitea (https://about.gitea.com/) que é um fork do projeto Gogs.
Por fim veio o Forgejo (https://forgejo.org/) que é um fork do Gitea.Ou seja: tem código fonte pra todo lado. 🤠
¶ Instalação em docker
Pre-requisito: Ter o Docker e Docker-Compose instalado
Além da documentação oficial ser bastante simples, um detalhe são as variáveis de ambiente que podem ser "anexadas" através do arquivo
.env, possibilitando definir algumas opções no momento que o container é inicializado.
Criando nosso diretório e arquivos
docker-compose.ymle.env
mkdir -p ~/docker/gitea/; cd ~/docker/gitea/
cat << '_EOF' > docker-compose.yml
services:
webapp:
image: "docker.gitea.com/gitea"
container_name: gitea
env_file:
- .env
restart: unless-stopped
volumes:
- ./gitea_data:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3002:3000"
- "2222:2222"
depends_on:
- db
db:
image: mariadb
container_name: mariadb-server
restart: unless-stopped
environment:
- MARIADB_ROOT_PASSWORD=${GITEA__database__ROOT_PASSWORD}
- MARIADB_USER=${GITEA__database__USER}
- MARIADB_PASSWORD=${GITEA__database__PASSWD}
- MARIADB_DATABASE=${GITEA__database__NAME}
volumes:
- ./mariadb_data:/var/lib/mysql
_EOF
cat << '_EOF' > .env
USER_UID=1000
USER_GID=1000
# Overall (DEFAULT)
APP_NAME=Gitea do Tiozão do Linux (:)
RUN_USER=git
RUN_MODE=prod
# Database (database)
GITEA__database__DB_TYPE=mysql
GITEA__database__HOST=db:3306
GITEA__database__NAME=gitea
GITEA__database__USER=gitea
GITEA__database__PASSWD=gitea
GITEA__database__ROOT_PASSWORD=Root_SQL_Password
# Repository (repository)
GITEA__repository__FORCE_PRIVATE=true
# Session
GITEA__session__PROVIDER=db
# Log
GITEA__log__ENABLE_SSH_LOG=true
GITEA__log__LEVEL=info
# Other
GITEA__other__SHOW_FOOTER_VERSION=true
GITEA__other__SHOW_FOOTER_TEMPLATE_LOAD_TIME=true
GITEA__other__SHOW_FOOTER_POWERED_BY=true
GITEA__other__ENABLE_SITEMAP=true
GITEA__other__ENABLE_FEED=true
# I18n
GITEA__i18n__LANGS="pt-BR,en-US"
GITEA__i18n__NAMES="Português do Brasil,English"
# UI (ui)
GITEA__ui__DEFAULT_THEME=gitea-dark
# Service (service)
GITEA__service__DISABLE_REGISTRATION=true
GITEA__service__REGISTER_EMAIL_CONFIRM=false
GITEA__service__ENABLE_NOTIFY_MAIL=true
GITEA__service__DEFAULT_KEEP_EMAIL_PRIVATE=false
GITEA__service__DEFAULT_ALLOW_CREATE_ORGANIZATION=false
GITEA__service__ENABLE_PASSKEY_AUTHENTICATION=false
GITEA__service__REQUIRE_SIGNIN_VIEW=true
# Service - Explore (service.explore)
GITEA__service.explore__REQUIRE_SIGNIN_VIEW=true
GITEA__service.explore__DISABLE_USERS_PAGE=false
GITEA__service.explore__DISABLE_ORGANIZATIONS_PAGE=false
# Mail (mailer)
GITEA__mailer__ENABLED=true
GITEA__mailer__FROM=Gitea Tiozão <[email protected]>
GITEA__mailer__PROTOCOL=smtps
GITEA__mailer__SMTP_ADDR=smtp.gmail.com
GITEA__mailer__PORT=465
[email protected]
GITEA__mailer__PASSWD=xxxxxxxxxxxxxxxx
# UI - Metadata (ui.meta)
GITEA__ui.meta__AUTHOR=Tioão do Linux
GITEA__ui.meta__DESCRIPTION=Gitea Self-Hosted Tiozão do Linux
# Server (server)
GITEA__server__ROOT_URL=https://gitea.tiozaodolinux.com
GITEA__server__DOMAIN=gitea.tiozaodolinux.com
GITEA__server__SSH_PORT=2222
GITEA__server__SSH_LISTEN_PORT=2222
GITEA__server__START_SSH_SERVER=true
# [openid]
GITEA__openid__ENABLE_OPENID_SIGNIN=false
GITEA__openid__ENABLE_OPENID_SIGNUP=false
# Time (time)<200b>
GITEA__time__DEFAULT_UI_LOCATION=America/Campo_Grande
# Migrations (migrations)
GITEA__migrations__ALLOWED_DOMAINS=*
GITEA__migrations__ALLOW_LOCALNETWORKS=true
GITEA__migrations__BLOCKED_DOMAINS=
# Admin (admin) Initial admin (NOT WORK)
#GITEA__admin__USERNAME=Gitea_Admin_User
#GITEA__admin__PASSWORD=xxxxxxxxxxxxxxxxxx
#[email protected]
_EOF
¶ Detalhes de algumas variáveis:
(1) GITEA__service__* permite ter um ambiente mais restrito, principalmente não deixar aberto o acesso anonimamente
(2) GITEA__mailter__* permite o envio emails. Tenho um Tutorial Completo mostrando como utilizar uma conta do Gmail pra enviar emails
(3) GITEA__other__* permite mostrar/esconder algumas informações no rodapé das páginas
(4) GITEA__i18n__* limita idiomas a apenas en_US e pt_BR
(5) GITEA__ui__* preferências globais da interface do usuário (ui)
(6) GITEA__server__* definição da URL e acesso SSH
Subir a stack com os containers gitea e mariadb
docker compose up -d && docker compose logs -f
¶ Validando o acesso
Acesse a URL definida na variável GITEA__server__ROOT_URL que no meu caso é https://gitea.tiozaodolinux.com
No primeiro acesso, será necessário criar um usuário/senha/email do Administrador. Existe uma solicitação que esse Administrador possa ser criado utilizando as configurações iniciais do .env https://github.com/go-gitea/gitea/issues/31671, mas ainda não foi aceito.
As demais variáveis de ambiente definidas no .env serão utilizadas.
Ao clicar no botão Install Gitea, o processo irá criar os volumes definidos no docker-compose.yml e iniciará na tela inicial já logado.
Eu prefiro manter a conta do Administrador no idioma English clicando no botão superior direito Perfil e Configurações -> Configurações do usuário -> Aparência -> Idioma -> English e confirme no botão Atualizar idioma.
(1) Detalhe interessante: o arquivo
data/custom/conf/app.inié gerado com as informações passadas pelas variáveis na primeira vez que o container é executado.
(2) Se for necessário alterar algum parâmetro do Gitea depois de já instanciado, basta alterar neste arquivo e restartar o container.
(3) Mais detalhes do que pode ser alterado você encontra aqui: https://docs.gitea.com/administration/config-cheat-sheet
Olhando as primeiras linhas do arquivo
app.ini
head gitea_data/gitea/conf/app.ini
APP_NAME = Gitea do Tiozão do Linux (:)
RUN_MODE = prod
RUN_USER = git
WORK_PATH = /data/gitea
[repository]
ROOT = /data/git/repositories
FORCE_PRIVATE = true
[repository.local]
Clique no botão superior direito Acessar e Sair
Clique no botão superior direito Acessar e entre com seu usuário/senha inicial.
¶ O que é Act Runner
O Act Runner é um aplicativo que funciona com o Gitea CI/CD para executar tarefas em um pipeline.
Normalmente o runner é executado em máquina devidamente preparada ser o servidor docker onde os Workflows irão ser executadas.
Porque na prática é melhor possuir três ambientes (DEV-Desenvolvimento, HOM-Homologação, PRD-Produção)?
Imagine um ambiente PRD com tudo funcionando e repentinamente um deploy de DEV equivocadamente é executado causando uma instabilidade no ambiente.
Com a separação desses ambientes garante-se um melhor controle do que está sendo executado.
Cada ambiente deve ser provido levando-se em conta a quantidade de recursos necessários suportar a execução dos containers.
¶ Obter o token de registro a nível de Instância (Global)
Clique no ícone do usuário Administrador criado e na opção Site Administration:
Em Admin Settings, vá em Actions -> Runners -> Create new Runner.
¶ Act Runner - Produção (Label PRD)
Acesse via ssh seu servidor de produção.
Criando nosso diretório e arquivos
docker-compose.ymle.env
mkdir -p ~/docker/act_runner/; cd ~/docker/act_runner
cat << '_EOF' > docker-compose.yml
# https://docs.gitea.com/usage/actions/act-runner
# create .env with enviroment variables
services:
runner:
image: gitea/act_runner
environment:
GITEA_INSTANCE_URL: "${INSTANCE_URL}"
GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
GITEA_RUNNER_NAME: "${RUNNER_NAME}"
GITEA_RUNNER_LABELS: "${RUNNER_LABELS}"
restart: unless-stopped
volumes:
- ./runner_data:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
- /var/run/docker.sock:/var/run/docker.sock
_EOF
cat << _EOF > .env
INSTANCE_URL="https://gitea.tiozaodolinux.com"
REGISTRATION_TOKEN="RF1T355BWPTI330uah8XwXTID3pQUMeIEki9w3Ym"
RUNNER_NAME="`hostname`"
RUNNER_LABELS="prd:docker://gitea/runner-images:ubuntu-latest,ubuntu-latest:docker://gitea/runner-images:ubuntu-latest"
_EOF
¶ Altere as variáveis no arquivo .env:
(1)
INSTANCE_URL- informe a URL GITEA__server__ROOT_URL do seu Gitea
(2)REGISTRATION_TOKEN- Registration Token gerado anteriormente
(3)RUNNER_NAME- pelo nome do seu Runner (por default utilize o hostname do seu host)
(4)RUNNER_LABELS- pelos Labels desejados que esse runner "atenda"
Agora podemos iniciar o container do runner e observar os logs:
docker compose up -d && docker compose logs -f
[+] Running 5/5
✔ runner Pulled 3.3s
✔ d69d4d41cfe2 Pull complete 0.7s
✔ 5cf0f10aedb4 Pull complete 0.9s
✔ 21998dee566d Pull complete 1.0s
✔ 9842ca1d4502 Pull complete 1.1s
[+] Running 2/2
✔ Network act_runner_default Created 0.3s
✔ Container act_runner-runner-1 Started 0.5s
runner-1 | .runner is missing or not a regular file
runner-1 | level=info msg="Registering runner, arch=arm64, os=linux, version=v0.2.12."
runner-1 | level=debug msg="Successfully pinged the Gitea instance server"
runner-1 | level=info msg="Runner registered successfully."
runner-1 | SUCCESS
runner-1 | time="2025-08-16T22:01:16Z" level=info msg="Starting runner daemon"
runner-1 | time="2025-08-16T22:01:16Z" level=info msg="runner: oracle-01.tiozaodolinux.com, with version: v0.2.12, with labels: [prd ubuntu-latest], declare successfully"
Se desejar conferir se o arquivo de configuração do runner foi criado corretamente:
cat runner-data/.runner | jq
¶ Act Runner - Homologação (Label HOM)
Acesse via ssh seu servidor de homologação.
Crie o docker-compose.yml igual ao de produção acima.👆👆👆👆
cat << _EOF > .env
INSTANCE_URL="https://gitea.tiozaodolinux.com"
REGISTRATION_TOKEN="RF1T355BWPTI330uah8XwXTID3pQUMeIEki9w3Ym"
RUNNER_NAME="`hostname`"
RUNNER_LABELS="hom:docker://gitea/runner-images:ubuntu-latest,ubuntu-latest:docker://gitea/runner-images:ubuntu-latest
_EOF
¶ Act Runner - Desenvolvimento (Label DEV)
Acesse via ssh seu servidor de desenvolvimento.
Crie o docker-compose.yml igual ao de produção acima.👆👆👆👆
cat << _EOF > .env
INSTANCE_URL="https://gitea.tiozaodolinux.com"
REGISTRATION_TOKEN="RF1T355BWPTI330uah8XwXTID3pQUMeIEki9w3Ym"
RUNNER_NAME="`hostname`"
RUNNER_LABELS="dev:docker://gitea/runner-images:ubuntu-latest,ubuntu-latest:docker://gitea/runner-images:ubuntu-latest
_EOF
¶ Conferindo o status dos runners no Gitea
Em Admin Settings, vá em Actions -> Runners
¶ Detalhes do runner
Name: identificação/nome do runner
Type:
- Global: Todos repositórios podem executar jobs com GitHub Actions workflows
- Organization: Atende todos os repositórios da organização
- Repository: Exclusivo para um determinado repositório
Labels: labels que esse runner atende para CI/CD
¶ Criando Organização/Repositório/Migration
¶ Uma Organização
No parâmetro Organization Name digite o nome da organização e click no botão Create Organization
¶ Um Repositório
No parâmetro Repository Name digite o nome do repositório e click no botão Create Repository
¶ Um Repositório Externo
Clique na imagem do GitHub
¶ Origem no GitHub
No parâmetro Migrate/Clone From URL cole https://github.com/Tiozao-do-Linux/github-actions.git e click no botão Migrate Repository
¶ GitHub Actions no Gitea
No repositório migrado github-actions clique em Actions -> exeute-commands.yml.
Na primeira execução o runner irá baixar as imagens (gitea/runner-images:ubuntu-latest, python:slim,
jarbelix/samba4-addc:debian, nginx) a serem utilizadas nos jobs com o label ubuntu-latest.
¶ Mostrando qual runner está rodando o workflow
¶ Mostrando a versão do nginx no job-04
¶ Gitea Autenticando no Active Directory
Em Admin Settings, vá em Identity & Access -> Autentication Sources -> Add Authentication Source.
Preencha com as configurações do seu Active Directory.
O quê? Não tem um Active Directory? Crie um agora 👉 em Samba-Active-Directory-Docker-Container 👈
Depois de confirmar as informações clicando em Add Autentication Source a autenticação com os usuários do Active Directory está ativa.
Minhas configurações em texto:
Authentication Type: LDAP (via BindDN)
Autehtication name: Active Directory
Security Protocol: LDAPS
Host: oracle-01.tiozaodolinux.com
Port: 636
(X) Skip TLS Verify
Bind DN: [email protected]
Bind Password: SuperSecretPassword@2025
User Search Base: CN=Users,DC=seudominio,DC=com,DC=br
User filter: (&(objectCategory=person)(objectClass=user)(!userAccountControl:1.2.840.113556.1.4.803:=2)(|(sAMAccountName=%[1]s)(mail=%[1]s)))
Username Attribute: sAMAccountName
First Name Attribute: givenName
Surname Attribute: sn
¶ Encontrou algum BUG no Gitea
Caso você descubra algum bug no Gitea sugiro que pesquise nas https://github.com/go-gitea/gitea/issues abertas antes de reportar. Atualmente já são mais de 2600 reports. Na minha opinião alguns são duplicados e indevidos.
O BUG que eu achei está aqui https://github.com/go-gitea/gitea/issues/35222. Vamos aguardar avaliação dos desenvolvedores ou alguém se dispuser a fazer um https://github.com/go-gitea/gitea/pulls e ser aprovado pelos desenvolvedores.
Para dirimir dúvidas e/ou sugestões entre no Grupo Tiozão do Linux
https://t.me/Grupo_Tiozao_Do_Linux
¶ Referências
¶ Documentação Oficial
- Installation with Docker - https://docs.gitea.com/next/installation/install-with-docker
- Act Runner (Gitea Actions) - https://docs.gitea.com/usage/actions/quickstart
- Act Runner (Register) - https://docs.gitea.com/usage/actions/act-runner#obtain-a-registration-token
- Authentication LDAP/AD - https://docs.gitea.com/usage/authentication
- Features Gitea Actions - https://blog.gitea.com/feature-preview-gitea-actions/
- Awesome Gitea - https://gitea.com/gitea/awesome-gitea/
¶ Documentação Auxiliar
- Authentication Example - https://github.com/lldap/lldap/blob/main/example_configs/gitea.md
- How to Build docker containers - https://medium.com/@lokanx/how-to-build-docker-containers-using-gitea-runners-600729555e07
- CI/CD - Full series - https://thehomelabber.com/series/self-hosted-git-with-gitea/
- Gitea: Como hospedar - https://blog.inedo.com/self-hosted/gitea/
- Set Default administrator username, email, and password - https://github.com/go-gitea/gitea/issues/31671
¶ Documentação Complementar
- Docker in Docker - https://www.docker.com/resources/docker-in-docker-containerized-ci-workflows-dockercon-2023/
- Docker
pull/push/tag/ls- https://docs.docker.com/reference/cli/docker/image/ - LDAP Search Filter Cheatsheet - https://gist.github.com/jonlabelle/0f8ec20c2474084325a89bc5362008a7
¶ Vídeos no Youtube
- Como usar GitHub Actions? - https://youtu.be/IKjcdYQvcDo?si=bmkNYIXt30UuNxQ4
- Entenda DevOps, CI e GITHUB ACTIONS de uma vez por todas - https://youtu.be/W_Fhjmsq7hU?si=3BJ8iJg_y4WwKjFx
- Building your own Git Server with Gitea on AlmaLinux - https://youtu.be/bVB24I7B0JQ?si=qhnKAYIBBr7rSGV5
- Hands-on Introduction to Gitea Actions - https://www.youtube.com/live/_2SBUOo6Nwk?si=0ftXfL94zyFJsy_R
- Criando um Workflow AUTOMATIZADO de CI com o Github Actions - https://youtu.be/F51HlrEeedw?si=fRA4ch1klz0qZ5fg&t=38
- Como Criar Pipeline Docker CI com Github Actions - https://youtu.be/4j3iL0iZAqk?si=SJtikA689rQWPTD6
- Gitea Actions (Private GitHub Actions) Setup & Usage | Gitea Complete Setup Guide - https://youtu.be/FyLzot01MCg?si=S3BI0bGol2YB5kLQ&t=769
- Private Self-Hosted GitHub Server | Gitea Complete Setup Guide - https://www.youtube.com/watch?v=B3J22RRb7rE&ab_channel=TroubleChuteLinux