Self-hosted

Crear la GitHub App

Forjar actúa en GitHub solo como una GitHub App que es tuya. Con ella entra la gente y con ella se instala en los repositorios.

Se hace una vez por instalación. En los ejemplos, tu dirección es https://forjar.example.com.

Crea la app

En GitHub: Settings › Developer settings › GitHub Apps › New GitHub App.

CampoValor
NameCualquiera único, por ejemplo forjar-acme
Homepage URLCualquiera
Callback URLhttps://forjar.example.com/api/auth/github/callback
Setup URLhttps://forjar.example.com/api/github/install/callback, con Redirect on update marcado
Request user authorization (OAuth) during installationSí
Webhook › ActiveSí
Webhook URLhttps://forjar.example.com/webhooks/github
Webhook secretUna cadena larga aleatoria: openssl rand -hex 32
Where can it be installedOnly on this account mientras seas el único equipo; Any account cuando otros equipos la instalen

Con la autorización de usuario activada, GitHub devuelve a quien instala a la Callback URL, no a la Setup URL. Forjar distingue una instalación de un inicio de sesión por el installation_id que trae.

Dale solo estos permisos

Permisos de repositorio. Todo lo demás queda en No access:

PermisoAccesoPara qué
ContentsRead and writeClonar, subir ramas forja/* y mergear
Pull requestsRead and writeAbrir PRs, leer los ficheros cambiados, mergear
Commit statusesRead and writeEl check forja/gate y leer los demás estados
ChecksRead-onlyLo que dice tu CI de un commit
IssuesRead-onlyRecibir los eventos de issues
MetadataRead-onlyObligatorio

Suscríbete a los eventos Issues, Pull request, Pull request review y Check run. No le des nunca el permiso Workflows: Forjar no debe editar .github/workflows.

Genera la clave y el secreto de cliente

  • Generate a private key y descarga el .pem.
  • Apunta el App ID de la parte de arriba.
  • En Client secrets, genera uno y apunta también el Client ID.

Dale a Forjar sus secretos

En el directorio de la instalación, guarda tres ficheros en secrets/ y dales permiso 660:

cp forjar-acme.private-key.pem secrets/github-app-private-key
nano secrets/github-webhook-secret        # pega el secreto del webhook
nano secrets/github-oauth-client-secret   # pega el client secret
chmod 660 secrets/github-*

Y en .env:

GITHUB_APP_ID=123456
GITHUB_CLIENT_ID=Iv23li...
FORJA_ADMIN_EMAILS=[email protected]

FORJA_ADMIN_EMAILS es el email verificado de tu cuenta de GitHub: te deja abrir la primera cuenta y crear el equipo. Aplica los cambios:

docker compose up -d

/api/capabilities responde ahora githubApp y cockpit como true.

Instálala en los repositorios

Entra en Forjar con GitHub y abre https://forjar.example.com/api/github/install. GitHub te pregunta dónde instalarla: elige Only select repositories y marca solo aquellos en los que Forjar puede trabajar. Al volver, la instalación queda vinculada a tu equipo y a ningún otro.

Protege la rama principal

El gate solo se cumple si GitHub lo exige. En cada repositorio instalado, crea un ruleset para la rama por defecto. Los pasos están en GitHub › Protege la rama principal; son los mismos en cloud.

Comprueba los webhooks

En la pestaña Advanced de la app, las entregas deben responder 202. Un 401 significa que secrets/github-webhook-secret no coincide con el secreto de la app.