Al desarrollar el proyecto mkdotenv me topé con una necesidad concreta: publicar también para macOS y, para ello, mantener un repositorio con el tap de Homebrew, en mi caso homebrew-mkdotenv.
El procedimiento que definí fue el siguiente: primero, desde las acciones de mkdotenv genero la fórmula de Homebrew; después clono el repositorio del tap; creo una rama y copio el archivo dentro de la carpeta Formula; verifico que la aplicación se instala; empujo la rama; por último, abro el pull request. Estos últimos pasos fueron los más problemáticos, así que detallo cómo los resolví.
Aplicaciones y ajustes necesarios
Paso 1 Instalar Qoomon Access Tokens para GitHub Actions. Utilicé el proyecto qoomon actions access token, que ofrece una GitHub App capaz de emitir tokens temporales durante la ejecución del workflow. Estos tokens permiten permisos granulares, como empujar ramas o abrir PRs en otros repositorios, algo que el GITHUB_TOKEN por defecto no siempre permite, y además es una alternativa más segura que almacenar un PAT en secretos. Lo instalé desde GitHub Marketplace. La configuración es gratuita, pero requiere pasar por el flujo de compra de GitHub a coste cero y facilitar datos básicos.
Tras instalar la app, hay que definir políticas de emisión mediante archivos YAML en dos niveles. Políticas globales en un repositorio llamado .github-access-token, donde se coloca un archivo access-token.yaml con las reglas generales sobre qué repositorios pueden solicitar tokens y qué operaciones se permiten. A modo de referencia, aquí está mi ejemplo público . Políticas locales en cada repositorio objetivo, es decir, donde se va a empujar o crear el PR, mediante el archivo .github/access-token.yaml. Debe corresponder con el propietario definido por la política global y actúa como confirmación por repositorio, acotando los permisos.
En mi caso gestiono tres repos: pc-magas/.github-access-token con la política general en access-token.yaml; pc-magas/homebrew-mkdotenv que recibe los PR; y pc-magas/mkdotenv donde se crea la fórmula, la acción crea y sube una rama en pc-magas/homebrew-mkdotenv con la nueva fórmula y finalmente abre un PR. Todos pertenecen al mismo propietario pc-magas.
El flujo resumido es este: el workflow de pc-magas/mkdotenv solicita un token a la app según la política global, clona pc-magas/homebrew-mkdotenv con ese token, crea la rama, sube cambios y abre el PR. Las políticas global y local garantizan que solo ese workflow, desde las referencias permitidas, obtenga los permisos justos para contenidos y pull requests.
Paso 2 Configurar la política global en el repo .github-access-token. Crea el repositorio .github-access-token y dentro un access-token.yaml. En mi configuración, la clave origin apunta a pc-magas/.github-access-token. En allowed-repository-permissions concedo acciones write, contents write y pull-requests write como techo de permisos posibles. En statements defino los sujetos autorizados y permisos extra. Por ejemplo, autorizo el ref dev del repo origin y el workflow release.yml en la rama dev, y concedo pull-requests write. En términos prácticos, origin siempre sigue el formato OWNER/.github-access-token y OWNER es el usuario u organización. Por ejemplo, para un propietario ellakcy sería ellakcy/.github-access-token. El sistema usa origin para localizar la política global y verificar si se puede emitir el token con los permisos solicitados. El bloque allowed-repository-permissions es el presupuesto máximo de permisos que podrá tener cualquier token emitido. En statements se concreta quién puede pedir tokens y qué permisos precisos obtiene cada sujeto. Puedes ampliar la política añadiendo más bloques si varios repos o flujos necesitan acceso. Como guía, existe un template oficial en este archivo de ejemplo.
Paso 3 Definir la política local en el repo donde se hará el PR. En el repositorio objetivo pc-magas/homebrew-mkdotenv coloqué .github/access-token.yaml. Allí indico origin pc-magas/homebrew-mkdotenv y, en statements, permito como sujeto repo pc-magas/mkdotenv con comodín de referencias dobles asterisco para cubrir ramas, workflows y entornos. En permissions concedo contents write y pull-requests write. Esta política local es un opt in explícito que dice acepto que ese repositorio y sus workflows puedan empujar y abrir PR aquí con los permisos listados.
Implementación de la GitHub Action
Mi workflow completo está público y aquí muestro lo esencial. El job relevante es test_homebrew. Primero hace checkout, descarga el artefacto con la fórmula para macOS, y después genera un token de la GitHub App con la acción qoomon. Allí declaro repository pc-magas/homebrew-mkdotenv y solicito permissions contents write y pull_requests write. Ese token temporal se expone en la salida del paso y lo paso a las siguientes tareas como variable de entorno GH_PAT.
Con GH_PAT configuro git con usuario github-actions y correo actions@github.com, clono el tap usando una URL con autenticación mediante x-access-token y la variable GH_PAT, entro en el repo, creo una rama con un nombre como test-update-formula y el número de ejecución. Luego preparo la fórmula creando la carpeta Formula y copiando mkdotenv.rb dentro. Después hago commit, push de la rama y abro el PR.
La apertura del PR la realizo contra la API REST de GitHub descrita en la documentación oficial en crear un pull request. Envío un POST al endpoint del repositorio de destino, autenticando con el mismo token temporal como portador, indicando título, rama head, base y cuerpo del PR. Recomiendo usar la opción de curl fail-with-body para que, si la API responde con un estado 4XX o 5XX, el paso falle y puedas ver con claridad el motivo sin que el pipeline continúe ocultando el problema.
Ideas clave y buenas prácticas. Genera tokens solo en tiempo de ejecución y con permisos mínimos necesarios. Declara con precisión los subjects de las políticas para limitar el alcance a ramas y workflows concretos. Evita PATs persistentes y secretos innecesarios, la app de qoomon te aporta control fino y auditoría. Autentica git sobre HTTPS con x-access-token para clonado y push no interactivos. Valida la instalación final para asegurar que la fórmula es correcta antes de abrir el PR.
Con este enfoque, mkdotenv publica de forma automatizada su fórmula en el tap de Homebrew externo, manteniendo seguridad, trazabilidad y permisos granulares sin recurrir a tokens personales de larga duración.