← Volver al listado de tecnologías ← Índice de Forgejo

Forgejo: SSH y tokens de acceso

28 de febrero de 2026 Por: Artiko

forgejosshtokensgpgseguridadautenticacion

Capitulo 8: SSH y tokens de acceso

Forgejo soporta multiples metodos de autenticacion para operaciones Git y acceso a la API. Elegir el metodo correcto depende del contexto: uso personal, CI/CD o scripts automatizados.

SSH Keys

Las claves SSH permiten autenticarte sin contrasena. Es el metodo recomendado para uso diario desde la linea de comandos.

Generar un par de claves

El algoritmo Ed25519 es el recomendado actualmente por su seguridad y rendimiento:

ssh-keygen -t ed25519 -C "[email protected]"

El comando te pedira:

Ubicacion del archivo: acepta el valor por defecto ~/.ssh/id_ed25519
Passphrase: una contrasena opcional que protege la clave privada. Se recomienda usarla

Esto genera dos archivos:

~/.ssh/id_ed25519 — clave privada (nunca compartas este archivo)
~/.ssh/id_ed25519.pub — clave publica (esta es la que subes a Forgejo)

Agregar la clave publica en Forgejo

Copia el contenido de la clave publica:

cat ~/.ssh/id_ed25519.pub

En Forgejo, ve a Settings > SSH / GPG Keys
Presiona Add Key
Pega el contenido en el campo Content
Asigna un nombre descriptivo (por ejemplo: “laptop-personal”)
Guarda

Probar la conexion

ssh -T [email protected]

Si la configuracion es correcta, veras un mensaje como:

Hi usuario! You've successfully authenticated, but Forgejo does not provide shell access.

Si tienes multiples claves SSH, puedes configurar cual usar para cada host en ~/.ssh/config:

Host tu-dominio.com
    HostName tu-dominio.com
    User git
    IdentityFile ~/.ssh/id_ed25519_forgejo

Deploy Keys

Las deploy keys son claves SSH asociadas a un repositorio especifico en lugar de a una cuenta de usuario. Son ideales para servidores de produccion y pipelines de CI que solo necesitan acceso a un repositorio.

Crear una deploy key

Genera un par de claves dedicado para el deploy (sin passphrase para automatizacion):

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_deploy_miproyecto -N ""

En el repositorio de Forgejo, ve a Settings > Deploy Keys
Presiona Add Deploy Key
Pega la clave publica (~/.ssh/id_ed25519_deploy_miproyecto.pub)
Asigna un nombre descriptivo
Activa Allow Write Access si el proceso necesita hacer push (por ejemplo, actualizar version en un archivo)

Uso en el servidor

Configura ~/.ssh/config en el servidor para usar la clave correcta:

Host tu-dominio.com
    HostName tu-dominio.com
    User git
    IdentityFile /home/deploy/.ssh/id_ed25519_deploy_miproyecto

Tokens de acceso personal

Los tokens son cadenas alfanumericas que reemplazan la contrasena en autenticacion HTTP y en llamadas a la API REST.

Crear un token

Ve a Settings > Applications
En la seccion Manage Access Tokens, ingresa un nombre descriptivo
Selecciona los scopes (alcances) que necesitas
Presiona Generate Token
Copia el token inmediatamente. Forgejo no lo mostrara de nuevo

Alcances disponibles

Scope	Descripcion
`repo`	Acceso completo a repositorios (lectura y escritura)
`repo:status`	Acceso a estados de commits (CI checks)
`public_repo`	Acceso a repositorios publicos unicamente
`admin:org`	Gestion de organizaciones
`admin:repo_hook`	Gestion de webhooks
`user`	Lectura y modificacion del perfil de usuario
`user:email`	Acceso a direcciones de email
`delete_repo`	Permiso para eliminar repositorios
`package`	Acceso al registro de paquetes
`admin:gpg_key`	Gestion de claves GPG
`admin:application`	Gestion de aplicaciones OAuth

Principio de minimo privilegio: otorga solo los scopes que la aplicacion necesita.

Usar el token en clonado HTTP

# En la URL directamente
git clone https://[email protected]/usuario/mi-proyecto.git

# O configurarlo como credencial
git remote set-url origin https://[email protected]/usuario/mi-proyecto.git

Usar el token en llamadas a la API

curl -H "Authorization: token mi-token-aqui" \
  https://tu-dominio.com/api/v1/repos/usuario/mi-proyecto

Firmas GPG

Las firmas GPG garantizan que los commits provienen de quien dice ser el autor. Forgejo muestra los commits firmados con un indicador de “Verified”.

Generar una clave GPG

gpg --full-generate-key

Opciones recomendadas:

Tipo de clave: RSA and RSA (opcion 1)
Tamano: 4096 bits
Expiracion: 1 o 2 anos (no uses “no expira” para claves personales)
Nombre y email: deben coincidir con tu email en Forgejo

Exportar la clave publica

# Listar las claves disponibles
gpg --list-secret-keys --keyid-format LONG

# La salida muestra algo como:
# sec   rsa4096/ABCD1234EFGH5678 2026-01-01 [SC]

# Exportar la clave publica
gpg --armor --export ABCD1234EFGH5678

Agregar la clave en Forgejo

Ve a Settings > SSH / GPG Keys
Selecciona la pestana GPG Keys
Pega el bloque completo que comienza con -----BEGIN PGP PUBLIC KEY BLOCK-----
Presiona Add Key

Configurar git para firmar automaticamente

# Indicar a git que clave usar
git config --global user.signingkey ABCD1234EFGH5678

# Firmar todos los commits automaticamente
git config --global commit.gpgsign true

# Firmar todos los tags automaticamente
git config --global tag.gpgsign true

A partir de ahora, cada git commit incluira una firma GPG verificada por Forgejo.

Buenas practicas de seguridad

Tokens:

No incluyas tokens en codigo fuente ni en archivos de configuracion versionados
Usa variables de entorno o gestores de secretos (como Vault o el sistema de secretos de Forgejo Actions)
Rota los tokens periodicamente, especialmente si sospechas que fueron expuestos
Crea un token distinto por aplicacion o servicio

Claves SSH:

Protege la clave privada con una passphrase
Usa deploy keys en lugar de claves de usuario para CI/CD
Elimina deploy keys cuando un servidor ya no las necesite

GPG:

Configura una fecha de expiracion en tus claves
Guarda una copia de respaldo de tu clave privada en un lugar seguro y offline

Siguiente: Capitulo 9: Issues - gestion de tareas —>