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.
| Campo | Valor |
|---|---|
| Name | Cualquiera único, por ejemplo forjar-acme |
| Homepage URL | Cualquiera |
| Callback URL | https://forjar.example.com/api/auth/github/callback |
| Setup URL | https://forjar.example.com/api/github/install/callback, con Redirect on update marcado |
| Request user authorization (OAuth) during installation | Sí |
| Webhook › Active | Sí |
| Webhook URL | https://forjar.example.com/webhooks/github |
| Webhook secret | Una cadena larga aleatoria: openssl rand -hex 32 |
| Where can it be installed | Only 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:
| Permiso | Acceso | Para qué |
|---|---|---|
| Contents | Read and write | Clonar, subir ramas forja/* y mergear |
| Pull requests | Read and write | Abrir PRs, leer los ficheros cambiados, mergear |
| Commit statuses | Read and write | El check forja/gate y leer los demás estados |
| Checks | Read-only | Lo que dice tu CI de un commit |
| Issues | Read-only | Recibir los eventos de issues |
| Metadata | Read-only | Obligatorio |
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.