Puedes ver los ejemplos de los ganchos de pre-recepción para GitHub Enterprise Server en el repositorio github/platform-samples
.
Escribir un script de ganchos de pre-recepción
Un script de gancho de pre-recepción se ejecuta en un ambiente de gancho de pre-recepción en tu instancia de GitHub Enterprise Server. Cuando creas un script de gancho de pre-recepción, considera las entradas, resultados, estado de salida y variables de ambiente.
Input (stdin
)
Después de que ocurre una subida y antes de que se actualice cualquier referencia para el repositorio remoto, el proceso de git-receive-pack
en tu instancia de GitHub Enterprise Server invoca el script de gancho de pre-recepción. La entrada estándar para el script, stdin
, es una secuencia que contiene una línea que cada referencia actualizará. Cada línea contiene el nombre anterior del objeto para la referencia, el nombre nuevo del objeto para la referencia, y el nombre completo de la referencia.
<old-value> SP <new-value> SP <ref-name> LF
Esta secuencia representa los siguientes argumentos.
Argumento | Descripción |
---|---|
<old-value> | El nombre anterior del objeto se almacena en la referencia. Cuando creas una referencia nueva, el valor es de 40 ceros. |
<new-value> | Nombre del objeto nuevo que se almacenará en la referencia. Cuando borras una referencia, el valor es de 40 ceros. |
<ref-name> | El nombre completo de la referencia. |
Para obtener más información sobre git-receive-pack
, consulta "git-receive-pack" en la documentación de Git. Para obtener más información sobre las referencias, consulta la sección "Referencias de Git" en Pro Git.
Output (stdout
)
La salida estándar para el script, stdout
, se pasa de vuelta al cliente. El usuario en la línea de comando o en la interface de usuario podrá ver cualquier declaración de tipo echo
.
Estado de salida
El estado de salida de un script de pre-recepción determina si la subida se aceptará.
Valor del estado de salida | Acción |
---|---|
0 | La subida será aceptada. |
no cero | La subida será rechazada. |
Variables del entorno
Adicionalmente a la entrada estándar de tu script de gancho de pre-recepción, stdin
, GitHub Enterprise Server pone a disposición las siguientes variables en el ambiente Bash para la ejecución de tu script. Para obtener más información sobre stdin
para tu script de gancho de pre-recepción, consulta la sección "Input(stdin
)".
Hay diversas variables de ambiente disponibles para tu script de gancho de pre-recepción dependiendo de lo que active a dicho script para su ejecución.
- Siempre disponible
- Disponible para subidas desde la interface web o API
- Disponible para las fusiones de solicitudes de cambio
- Disponible para las subidas utilizando autenticación por SSH
Siempre disponible
Las siguientes variables siempre están disponibles en el ambiente de gancho de pre-recepción.
Variable | Descripción | Valor de ejemplo |
---|---|---|
$GIT_DIR | Ruta al repositorio remoto en la instancia | /data/user/repositories/a/ab/ a1/b2/34/100001234/1234.git |
$GIT_PUSH_OPTION_COUNT | La cantidad de opciones de subida que envió el cliente con --push-option . Para obtener más información, consulta la sección "git-push" en la documentación de Git. | 1 |
$GIT_PUSH_OPTION_N | Donde N es un número entero que comienza con 0, esta variable contiene la cadena de opción de subida que envió el cliente. La primera opción que se envió se almacena en GIT_PUSH_OPTION_0 , la segunda opción que se envió se almacena en GIT_PUSH_OPTION_1 , y así sucesivamente. Para obtener más información sobre las opciones de subida, consulta "git-push" en la documentación de Git. | abcd |
$GIT_USER_AGENT | El cliente de Git que subió los cambios envía la secuencia de usuario-agente | git/2.0.0 |
$GITHUB_REPO_NAME | Nombre del repositorio que se está actualizando en formato NAME/OWNER | octo-org/hello-enterprise |
$GITHUB_REPO_PUBLIC | Valor booleano que representa si el repositorio que se está actualizando es público |
|
$GITHUB_USER_IP | La dirección IP del cliente que inició la subida | 192.0.2.1 |
$GITHUB_USER_LOGIN | El nombre de usuario de la cuenta que inició la subida | octocat |
Disponible para subidas desde la interface web o API
La variable $GITHUB_VIA
se encuentra disponible en el ambiente de gancho de pre-recepción cuando la actualización de la referencia que activa el gancho ocurre a través ya sea de la interface web o de la API para GitHub Enterprise Server. El valor describe la acción que actualizó la referencia.
Valor | Acción | Más información |
---|---|---|
auto-merge deployment api | Fusión automática de la rama base a través del despliegue que se creó con la API | "Crear un despliegue" en la documentación de la API de REST |
blob#save | Cambio al contenido de un archivo en la interface web | "Editar archivos" |
branch merge api | Fusión de una rama a través de la API | "Fusionar una rama" en la documentación de la API de REST |
branches page delete button | Borrado de una rama en la interface web | "Crear y borrar ramas dentro de tu repositorio" |
git refs create api | Creación de una referencia a través de la API | "Base de datos de Git" en la documentación de la API de REST |
git refs delete api | Borrado de una referencia a través de la API | "Bases de datos de Git" En la documentación de la API de REST |
git refs update api | Actualización de una referencia a tracvés de la API | "Base de datos de Git" en la documentación de la API de REST |
git repo contents api | Cambio al contenido de un archivo a través de la API | "Crear o actualizar el contenido de un archivo" en la API de REST |
|
merge
| Fusión de una solicitud de cambios utilizando la fusión automática | "Fusionar una solicitud de cambios automáticamente" |
|
merge base into head| Actualización de la rama de tema desde la rama base cuando la rama base requiere verificaciones de estado estrictas (a través de Actualizar rama en una solicitud de cambios, por ejemplo) | "Acerca de las ramas protegidas" | |
pull request branch delete button| Borrado de una rama de tema de una solicitud de cambios en la interfaz web | "Borrar y restablecer ramas en una solicitud de cambios" | |
pull request branch undo button| Restablecimiento de una rama de tema desde una solilcitud de cambios en la interfaz web| "Borrar y restablecer ramas en una solicitud de cambios" | |
pull request merge api| Fusión de una solicitud de cambios a través de la API | "Pulls" en la documentación de la API de REST | |
pull request merge button| Fusión de una solicitud de cambios en la interfaz web | "Fusionar una solicitude de cambios" | |
pull request revert button| Reversión de una solicitud de cambios | "Revertir una solicitud de cambios" | |
releases delete button| Borrado de un lanzamiento | "Administrar lanzamientos en un repositorio" | |
stafftools branch restore| Restablecimiento de una rama desde el tablero de administrador de sitio | "Tablero de administrador de sitio" | |
tag create api| Creación de una etiqueta a través de la API | "Git database" en la documentación de la API de REST | |
slumlord (#SHA)| Confirmar a través de Subversion | "Soporte para clientes de Subversion" | |
web branch create| Creación de una rama a través de la interfaz web | "Crear y borrar ramas dentro de tu repositorio" |
Disponible para las fusiones de solicitudes de cambio
Las siguientes variables se encuentran disponibles en el ambiente de gancho de pre-recepción cuando la subida que activa el gancho se debe a la fusión de una solicitud de cambios.
Variable | Descripción | Valor de ejemplo |
---|---|---|
$GITHUB_PULL_REQUEST_AUTHOR_LOGIN | Nombre de usuario de la cuenta que creó la solicitud de cambios | octocat |
$GITHUB_PULL_REQUEST_HEAD | El nombre de la rama de tema de la solicitud de cambios en el formato USERNAME:BRANCH | |
$GITHUB_PULL_REQUEST_BASE | El nombre de la rama base de la solicitud de cambios en el formato USERNAME:BRANCH | octocat:main |
Disponible para las subidas utilizando autenticación por SSH
Variable | Descripción | Valor de ejemplo |
---|---|---|
$GITHUB_PUBLIC_KEY_FINGERPRINT | La huella dactilar de la llave pública para el usuario que subió los cambios | a1:b2:c3:d4:e5:f6:g7:h8:i9:j0:k1:l2:m3:n4:o5:p6 |
Establecer permisos y subidas a un ganchos de pre-recepción para GitHub Enterprise Server
Un script de gancho de pre-recepción se contiene en un repositorio de tu instancia de GitHub Enterprise Server. Un administrador del sitio debe tener en cuenta los permisos del repositorio y garantizar que solo los usuarios correspondientes tengan acceso.
Recomendamos los ganchos de consolidación a un solo repositorio. Si el repositorio de gancho consolidado es público, README.md
puede usarse para explicar los cumplimientos de la política. Además, las contribuciones pueden aceptarse mediante solicitudes de extracción. Sin embargo, los ganchos de pre-recepción solo pueden agregarse desde la rama por defecto. Para un flujo de trabajo de prueba, se deben usar las bifurcaciones del repositorio con la configuración.
-
Para usuarios de Mac, asegúrate de que los scripts tengan permisos de ejecución:
$ sudo chmod +x SCRIPT_FILE.sh
Para usuarios de Windows, asegúrate de que los scripts tengan permisos de ejecución:
git update-index --chmod=+x SCRIPT_FILE.sh
-
Confirma y sube al repositorio designado para los ganchos de pre-recepción en tu instancia de GitHub Enterprise Server.
$ git commit -m "YOUR COMMIT MESSAGE" $ git push
-
Crear el gancho de pre-recepción en la instancia de GitHub Enterprise Server.
Probar scripts de pre-recepción localmente
Puedes probar un script de gancho de pre-recepción localmente antes de que lo crees o actualices en tu instancia de GitHub Enterprise Server. Un método es crear un entorno de Docker local para que actúe como un repositorio remoto que pueda ejecutar el gancho de pre-recepción.
-
Asegúrate de que Docker se instaló localmente.
-
Crear un archivo denominado
Dockerfile.dev
que contenga:FROM gliderlabs/alpine:3.3 RUN \ apk add --no-cache git openssh bash && \ ssh-keygen -A && \ sed -i "s/#AuthorizedKeysFile/AuthorizedKeysFile/g" /etc/ssh/sshd_config && \ adduser git -D -G root -h /home/git -s /bin/bash && \ passwd -d git && \ su git -c "mkdir /home/git/.ssh && \ ssh-keygen -t ed25519 -f /home/git/.ssh/id_ed25519 -P '' && \ mv /home/git/.ssh/id_ed25519.pub /home/git/.ssh/authorized_keys && \ mkdir /home/git/test.git && \ git --bare init /home/git/test.git" VOLUME ["/home/git/.ssh", "/home/git/test.git/hooks"] WORKDIR /home/git CMD ["/usr/sbin/sshd", "-D"]
-
Crear un script de pre-recepción de prueba denominado
always_reject.sh
. Este script del ejemplo rechazará todas las subidas, lo cual es útil para bloquear un repositorio:#!/usr/bin/env bash echo "error: rejecting all pushes" exit 1
-
Asegúrate de que los scripts
always_reject.sh
tengan permisos de ejecución:$ chmod +x always_reject.sh
-
Desde el directorio que contiene
Dockerfile.dev
, crea una imagen:$ docker build -f Dockerfile.dev -t pre-receive.dev . > Sending build context to Docker daemon 3.584 kB > Step 1 : FROM gliderlabs/alpine:3.3 > ---> 8944964f99f4 > Step 2 : RUN apk add --no-cache git openssh bash && ssh-keygen -A && sed -i "s/#AuthorizedKeysFile/AuthorizedKeysFile/g" /etc/ssh/sshd_config && adduser git -D -G root -h /home/git -s /bin/bash && passwd -d git && su git -c "mkdir /home/git/.ssh && ssh-keygen -t ed25519 -f /home/git/.ssh/id_ed25519 -P ' && mv /home/git/.ssh/id_ed25519.pub /home/git/.ssh/authorized_keys && mkdir /home/git/test.git && git --bare init /home/git/test.git" > ---> Running in e9d79ab3b92c > fetch http://alpine.gliderlabs.com/alpine/v3.3/main/x86_64/APKINDEX.tar.gz > fetch http://alpine.gliderlabs.com/alpine/v3.3/community/x86_64/APKINDEX.tar.gz ....truncated output.... > OK: 34 MiB in 26 packages > ssh-keygen: generating new host keys: RSA DSA ECDSA ED25519 > Password for git changed by root > Generating public/private ed25519 key pair. > Your identification has been saved in /home/git/.ssh/id_ed25519. > Your public key has been saved in /home/git/.ssh/id_ed25519.pub. ....truncated output.... > Initialized empty Git repository in /home/git/test.git/ > Successfully built dd8610c24f82
-
Ejecutar un contenedor de datos que contiene una clave SSH generada:
$ docker run --name data pre-receive.dev /bin/true
-
Copiar el ganchos de pre-recepción de prueba
always_reject.sh
en el contenedor de datos:$ docker cp always_reject.sh data:/home/git/test.git/hooks/pre-receive
-
Poner en marcha un contenedor de la aplicación que corre
sshd
y ejecuta el gancho. Toma nota del id del contenedor que se devolvió:$ docker run -d -p 52311:22 --volumes-from data pre-receive.dev > 7f888bc700b8d23405dbcaf039e6c71d486793cad7d8ae4dd184f4a47000bc58
-
Copilar la clave SSH generada desde el contenedor de datos hasta la máquina local:
$ docker cp data:/home/git/.ssh/id_ed25519 .
-
Modificar el remoto de un repositorio de prueba y subirlo al repositorio
test.git
dentro del contenedor Docker. Este ejemplo utilizagit@github.com:octocat/Hello-World.git
, pero puedes utilizar cualquier repositorio que quieras. Este ejemplo asume que tu máquina local (127.0.01) es el puerto vinculante 52311, pero puedes usar una dirección IP diferente si el docker está ejecutándose en una máquina remota.$ git clone git@github.com:octocat/Hello-World.git $ cd Hello-World $ git remote add test git@127.0.0.1:test.git $ GIT_SSH_COMMAND="ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 52311 -i ../id_ed25519" git push -u test main > Warning: Permanently added '[192.168.99.100]:52311' (ECDSA) to the list of known hosts. > Counting objects: 7, done. > Delta compression using up to 4 threads. > Compressing objects: 100% (3/3), done. > Writing objects: 100% (7/7), 700 bytes | 0 bytes/s, done. > Total 7 (delta 0), reused 7 (delta 0) > remote: error: rejecting all pushes > To git@192.168.99.100:test.git > ! [remote rejected] main -> main (pre-receive hook declined) > error: failed to push some refs to 'git@192.168.99.100:test.git'
Observa que la subida fue rechazada después de ejecutar el ganchos de pre-recepción y de hace eco la salida del script.
Leer más
- "Personalizar Git - Un ejemplo de la política activa de Git" desde el sitio web de Pro Git