Ha pasado un año desde que lanzamos la primera versión pública de GitHub CLI.
Desde entonces, hemos agregado funcionalidad para administrar repositorios, comentar problemas, habilitar la fusión automática para solicitudes de extracción, configurar de forma segura valores secretos para acciones de GitHub y más.
Sin embargo, donde las herramientas de línea de comandos realmente brillan es en su capacidad para combinarse con otras utilidades e integrarse en scripts para capturar flujos de trabajo que pueden ser específicos para usted o su equipo.
Entonces, para celebrar un año con GitHub CLI, exploremos cómo podemos personalizar y construir sobre el COMANDO gh.
Los emuladores de terminal, los shells y las herramientas de línea de comandos están omnipresentes porque se basan en la idea de que el texto sin formato es la interfaz universal, que se pasa fácilmente entre procesos a través de flujos de entrada / salida.
En los siguientes ejemplos, usaremos GitHub CLI 1.7+ para capturar diferentes flujos de trabajo de GitHub aprovechando estos conceptos.
Haz tuyo el gh
La forma más básica de comenzar a extender las herramientas de línea de comandos es explorar sus opciones de personalización. Por ejemplo, para evitar escribir nombres de comandos largos y sus banderas en su totalidad, podemos definir alias para ellos:
# before:
$ gh issue view --comments https://github.com/cli/cli/issues/1055
# configure an alias:
$ gh alias set iv 'issue view --comments'
# after:
$ gh iv https://github.com/cli/cli/issues/1055
Otra opción que puedes configurar es definir un localizador de terminal. Si ejecutas el comando issue view, puede notar que, debido al tamaño del hilo de conversación, la salida del comando llena varias pantallas y que para comenzar a leer desde la parte superior, primero debemos desplazarte hacia atrás.
Para ayudarte a evitar tener que hacer esto cada vez para una salida larga, debes hacer que gh respete la configuración de la variable de entorno PAGER pasando toda la salida a través de la utilidad de búsqueda especificada:
$ PAGER=less gh issue view -c https://github.com/cli/cli/issues/1055
El less permite moverse hacia arriba / abajo con las teclas del teclado y buscar dentro de la salida escribiendo “/”. Para salir, presiona “q”.
Nota de compatibilidad para usuarios de Windows: si desea seguir estos ejemplos, ingrese los comandos desde el Git Bash que viene incluido con Git para Windows.
Además de los buscadores comunes como less, también hay otros para propósitos específicos. Por ejemplo, delta es una utilidad para formatear la salida de git diff. Después de instalarlo con Homebrew u otro administrador de paquetes, podemos usarlo para ver los cambios en una solicitud de extracción como una consola dividida:
$ brew install git-delta
$ PAGER='delta -s' gh pr diff https://github.com/cli/cli/pull/3023
Finalmente, para definir un buscador para todos los comandos gh de forma predeterminada, puedes establecer una opción en la configuración:
$ gh config set pager 'delta -s'
Después de esto, la salida larga de los comandos gh ya no debería ser un problema.
Combinar gh con otras herramientas
El comando gh pr list imprime solicitudes de extracción abiertas para el repositorio actual.
Sin embargo, para buscar un elemento específico y actuar en consecuencia, es posible que deba examinar toda la lista.
Seleccionar un elemento específico de la lista podría ser más fácil con la ayuda de herramientas de búsqueda como fzf:
$ brew install fzf
$ gh pr list | fzf
#=> [selected item]
La utilidad fzf permite filtrar interactivamente el flujo de entrada e imprimir la línea seleccionada como salida.
Después de eso, puedes aislar solo el número de solicitud de extracción de la salida usando cut y reenviarlo como un argumento a otro comando gh.
Por ejemplo, aquí hay un alias para poder verificar rápidamente una solicitud de extracción de la lista de solicitudes abiertas:
$ gh alias set co --shell 'id="$(gh pr list -L100 | fzf | cut -f1)"; [ -n "$id" ] && gh pr checkout "$id"'
$ gh co
#=> [checkout the selected PR]
En general, cuando gh detecta que la salida se canaliza a un script en lugar de imprimirse en el terminal, tiende a formatear la salida en un formato más legible por la máquina: Los campos están delimitados por tabulaciones y no hay secuencias de escape para el color en la salida.
Esto permite que los scripts reciban y tengan un control total sobre los datos sin procesar de gh.
Usar gh junto a las Acciones de Github
La CLI de GitHub viene preinstalada en los entornos virtuales de Acciones de GitHub. Si no existe ninguna acción en la Marketplace para realizar una tarea específica, es posible que puedas crear un script de flujo de trabajo mediante la CLI de GitHub.
Por ejemplo, este paso del flujo de trabajo marcará cada nueva solicitud de extracción para que se combine automáticamente cuando se cumplan todos los requisitos:
steps:
- name: Enable auto-merge for new PRs
run: gh pr merge --auto --merge "$PR_URL"
env:
PR_URL: ${{github.event.pull_request.html_url}}
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
Este enfoque podría ampliarse para marcar solo algunas solicitudes de extracción para que se fusionen automáticamente; por ejemplo, los abiertos por miembros del equipo central en un proyecto de código abierto.
Otro flujo de trabajo crea automáticamente una versión de GitHub para cada etiqueta de git y carga los activos de compilación en ella:
- name: Create a release and attach files
run: |
tagname="${GITHUB_REF#refs/tags/}"
gh release create "$tagname" dist/*.tgz
env:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
Puede ver la configuración completa del flujo de trabajo para estos ejemplos aquí. Siempre que GITHUB_TOKENse establezca en el entorno de Acciones de Github, y se habilite gh puede ser habilitado convenientemente.
Además, si tus script necesitan escribirse en repositorios distintos al actual, puedes generar un token de acceso personal y agregarlos al repositorio usando gh secret set.
Accede a cualquier cosa con gh api
Para las operaciones en las que la CLI de GitHub actualmente no tiene sus propios comandos dedicados, siempre existe la API de GitHub.
Inspirado en curl el comando gh api puede realizar cualquier operación REST o GraphQL y manejar tareas como autenticación, serialización de parámetros y decodificación JSON.
Por ejemplo, digamos que queremos responder a la pregunta: ¿Cuál de los problemas en un repositorio propiedad de una organización involucra a miembros de un equipo específico?
En los términos de búsqueda de GitHub, la participación en un problema significa que un miembro comentó, fue mencionado o fue asignado a uno.
Una consulta de búsqueda para responder a esta pregunta sería algo como:, is:issue is:open involves:user1 involves:user2 pero dado que los equipos pueden cambiar con el tiempo, necesitaríamos construir esa consulta de forma dinámica.
Comencemos por enumerar a todos los miembros de un equipo de organización. Con curl, la solicitud sería algo como:
$ curl https://api.github.com/orgs/MYORG/teams/TEAM/members
Con gh api obtenemos el almacenamiento en caché de paginación y la respuesta de forma gratuita:
$ gh api -X GET 'orgs/MYORG/teams/TEAM/members' -F per_page=100 --paginate --cache 1h
[
{
"login": "user1",
"id": 1234,
...
},
...
]
La salida JSON sin formato puede ser difícil de manejar desde los scripts de shell. Al agregar una expresión de filtro jq, podemos seleccionar solo los campos que queremos, por ejemplo, todos los identificadores de inicio de sesión del usuario:
$ gh api ... --jq '.[].login'
#=> "user1"
#=> "user2"
#=> ...
Al modificar ligeramente la expresión, podemos obtener todos los miembros listados en un formato que se asemeja a la consulta de búsqueda que queremos:
$ gh api ... --jq '[.[].login] | map("involves:\(.)") | join(" ")'
#=> "involves:user1 involves:user2"
En el paso final, podemos pasar eso a una consulta final de la que enumeramos los resultados de:
team-involves() {
gh api -X GET "orgs/$1/teams/$2/members" \
-F per_page=100 --paginate --cache 1h \
--jq '[.[].login] | map("involves:\(.)") | join(" ")'
}
gh api -X GET search/issues -F per_page=100 --paginate \
-f q="repo:MYORG/REPO is:issue is:open $(team-involves MYORG TEAM)" \
--jq '.items[] | [.number, .title] | @tsv'
#=> "456 Issue title"
#=> "123 Another issue"
#=> ...
El resultado final enumera el número y el título de cada tema coincidente, uno por línea. Por supuesto, se pueden imprimir más propiedades expandiendo la expresión jq.
Para obtener la lista de todas las propiedades disponibles sobre un problema, consulte la documentación de la API.
¿Cómo instalar la CLI de Github?
GitHub CLI es una herramienta versátil con la que crear sus flujos de trabajo.
Fuente: Blog Oficial de Github