En este artículo se describe cómo empezar a usar la API REST de GitHub mediante GitHub CLI, JavaScript o curl
. Para ver una guía más detallada, consulta "Introducción a la API REST".
Cómo empezar a usar GitHub CLI
Usar GitHub CLI en la línea de comandos
GitHub CLI es la forma más sencilla de utilizar la API de REST de GitHub desde la línea de comandos.
Nota: El ejemplo siguiente está pensado para GitHub.com. Si prefieres probar el ejemplo con GitHub AE, debes reemplazar octocat/Spoon-Knife
por un repositorio en GitHub AE. Como alternativa, vuelve a ejecutar el comando gh auth login
para autenticarte en GitHub.com en lugar de GitHub AE.
-
Instala GitHub CLI si aún no lo has hecho. A fin de obtener instrucciones de instalación, consulta el repositorio de GitHub CLI.
-
Usa el subcomando
auth login
para autenticarte en GitHub CLI. Para obtener más información, consulta la documentación deauth login
GitHub CLI.gh auth login
-
Usa el subcomando
api
para realizar la solicitud de API. Para obtener más información, consulta la documentación deapi
GitHub CLI.gh api repos/octocat/Spoon-Knife/issues
Uso de GitHub CLI en GitHub Actions
También puedes usar GitHub CLI en los flujos de trabajo de GitHub Actions. Para obtener más información, vea «Utilizar el CLI de GitHub en los flujos de trabajo».
En lugar de usar el comando gh auth login
, pasa el token de acceso como una variable de entorno denominada GH_TOKEN
. GitHub recomienda autenticarse con el GITHUB_TOKEN
integrado en lugar de crear un token. Si esto no es posible, almacena el token como secreto y reemplaza GITHUB_TOKEN
en el ejemplo siguiente por el nombre del secreto. Para obtener más información sobre GITHUB_TOKEN
, consulta "Autenticación automática de tokens". Para obtener más información sobre secretos, consulte "Using secrets in GitHub Actions".
Nota: Los flujos de trabajo de ejemplo siguientes están pensados para GitHub.com. Si prefieres probar los ejemplos con GitHub AE, debes reemplazar octocat/Spoon-Knife
por un repositorio en GitHub AE.
on:
workflow_dispatch:
jobs:
use_api:
runs-on: ubuntu-latest
permissions:
issues: read
steps:
- env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh api repos/octocat/Spoon-Knife/issues
Si está autenticando con un GitHub App, puedes crear un token de acceso de instalación en el flujo de trabajo:
-
Almacena la ID de tu GitHub App como un secreto. En el flujo de trabajo siguiente, reemplaza
APP_ID
por el nombre del secreto. Puedes encontrar tu ID de app en la página de ajustes de tu app o mediante la API. Para más información, consulta "Aplicaciones de GitHub" en la documentación de REST API. Para obtener más información sobre secretos, consulte "Using secrets in GitHub Actions". -
Generar una llave privada para tu app. Almacena el contenido del archivo resultante como un secreto. (Almacena todo el contenido del archivo, incluido el contenido de
-----BEGIN RSA PRIVATE KEY-----
y-----END RSA PRIVATE KEY-----
). En el siguiente ejemplo, reemplazaAPP_PEM
por el nombre del secreto. Para obtener más información, vea «Administración de claves privadas para aplicaciones de GitHub». -
Agrega un paso para generar un token y use ese token en lugar de
GITHUB_TOKEN
. Ten en cuenta que este token expirará después de 60 minutos. Por ejemplo:on: workflow_dispatch: jobs: track_pr: runs-on: ubuntu-latest steps: - name: Generate token id: generate_token uses: actions/create-github-app-token@v1 with: app_id: ${{ secrets.APP_ID }} private_key: ${{ secrets.APP_PEM }} - name: Use API env: GH_TOKEN: ${{ steps.generate_token.outputs.token }} run: | gh api repos/octocat/Spoon-Knife/issues
Introducción al uso de JavaScript
Puedes usar Octokit.js para interactuar con la API de REST de GitHub en los scripts de JavaScript. Para obtener más información, consulta "Scripting con la API de REST y JavaScript".
Uso de Octokit.js
Nota: El ejemplo siguiente está pensado para GitHub.com. Si prefieres probar el ejemplo con GitHub AE, debes reemplazar octocat/Spoon-Knife
por un repositorio en GitHub AE. Como alternativa, puedes crear una nueva instancia de Octokit
sin especificar baseURL
.
-
Creación de un token de acceso. Por ejemplo, cree un personal access token o un token de acceso de usuario GitHub App. Para más información, consulta "Creación de un personal access token" o "Identificación y autorización de usuarios para aplicaciones de GitHub".
Advertencia: trata el token de acceso igual que una contraseña.
Para proteger el token, puedes almacenar el token como secreto y ejecutar el script a través de GitHub Actions. Para obtener más información, consulta la sección "Uso de Octokit.js en GitHub Actions".
Si estas opciones no son posibles, considera el uso de otro servicio de CLI para almacenar el token de forma segura.
-
Instalar
octokit
. Por ejemplo,npm install octokit
. Para ver otras formas de instalar o cargaroctokit
, consulta el archivo README de Octokit.js. -
Importar
octokit
en tu script. Por ejemplo,import { Octokit } from "octokit";
. Para obtener otras formas de importaroctokit
, consulta el archivo README de Octokit.js. -
Crea una instancia de
Octokit
con tu token. ReemplaceYOUR-TOKEN
por su token.const octokit = new Octokit({ auth: 'YOUR-TOKEN' });
-
Usa
octokit.request
para ejecutar la solicitud. Envía el método HTTP y la ruta de acceso como primer argumento. Especifica cualquier parámetro de ruta de acceso, consulta y cuerpo en un objeto como segundo argumento. Por ejemplo, en la siguiente solicitud, el método HTTP esGET
, la ruta de acceso es/repos/{owner}/{repo}/issues
y los parámetros sonowner: "octocat"
yrepo: "Spoon-Knife"
.await octokit.request("GET /repos/{owner}/{repo}/issues", { owner: "octocat", repo: "Spoon-Knife", });
Uso de Octokit.js en GitHub Actions
También puedes ejecutar los scripts de JavaScript en los flujos de trabajo de GitHub Actions. Para obtener más información, vea «Sintaxis del flujo de trabajo para Acciones de GitHub».
GitHub recomienda autenticarse con el GITHUB_TOKEN
integrado en lugar de crear un token. Si esto no es posible, almacena el token como secreto y reemplaza GITHUB_TOKEN
en el ejemplo siguiente por el nombre del secreto. Para obtener más información sobre GITHUB_TOKEN
, consulta "Autenticación automática de tokens". Para obtener más información sobre secretos, consulte "Using secrets in GitHub Actions".
Nota: El ejemplo siguiente está pensado para GitHub.com. Si prefieres probar el ejemplo con GitHub AE, debes reemplazar octocat/Spoon-Knife
por un repositorio en GitHub AE. Como alternativa, puedes crear una nueva instancia de Octokit
sin especificar baseURL
.
Observa el siguiente flujo de trabajo de ejemplo:
- Comprueba el contenido del repositorio
- Configura Node.js
- Instala
octokit
- Almacena el valor de
GITHUB_TOKEN
como una variable de entorno denominadaTOKEN
y ejecuta.github/actions-scripts/use-the-api.mjs
, que puede tener acceso a esa variable de entorno comoprocess.env.TOKEN
Ejemplo de flujo de trabajo:
on:
workflow_dispatch:
jobs:
use_api_via_script:
runs-on: ubuntu-latest
permissions:
issues: read
steps:
- name: Check out repo content
uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '16.17.0'
cache: npm
- name: Install dependencies
run: npm install octokit
- name: Run script
run: |
node .github/actions-scripts/use-the-api.mjs
env:
TOKEN: ${{ secrets.GITHUB_TOKEN }}
Script de JavaScript de ejemplo, con la ruta de acceso del archivo .github/actions-scripts/use-the-api.mjs
:
import { Octokit } from "octokit"
const octokit = new Octokit({
auth: process.env.TOKEN
});
try {
const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
owner: "octocat",
repo: "Spoon-Knife",
});
const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})
console.log(titleAndAuthor)
} catch (error) {
console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}
Si está autenticando con un GitHub App, puedes crear un token de acceso de instalación en el flujo de trabajo:
-
Almacena la ID de tu GitHub App como un secreto. En el flujo de trabajo siguiente, reemplaza
APP_ID
por el nombre del secreto. Puedes encontrar tu ID de app en la página de ajustes de tu app o mediante la API de la misma. Para obtener más información, vea «Aplicaciones de GitHub». Para obtener más información sobre secretos, consulte "Using secrets in GitHub Actions". -
Generar una llave privada para tu app. Almacena el contenido del archivo resultante como un secreto. (Almacena todo el contenido del archivo, incluido el contenido de
-----BEGIN RSA PRIVATE KEY-----
y-----END RSA PRIVATE KEY-----
). En el siguiente ejemplo, reemplazaAPP_PEM
por el nombre del secreto. Para obtener más información, vea «Administración de claves privadas para aplicaciones de GitHub». -
Agrega un paso para generar un token y use ese token en lugar de
GITHUB_TOKEN
. Ten en cuenta que este token expirará después de 60 minutos. Por ejemplo:on: workflow_dispatch: jobs: use_api_via_script: runs-on: ubuntu-latest steps: - name: Check out repo content uses: actions/checkout@v4 - name: Setup Node uses: actions/setup-node@v4 with: node-version: '16.17.0' cache: npm - name: Install dependencies run: npm install octokit - name: Generate token id: generate_token uses: actions/create-github-app-token@v1 with: app_id: ${{ secrets.APP_ID }} private_key: ${{ secrets.APP_PEM }} - name: Run script run: | node .github/actions-scripts/use-the-api.mjs env: TOKEN: ${{ steps.generate_token.outputs.token }}
Introducción al uso de curl
Uso de curl
en la línea de comandos
Notas:
- El ejemplo siguiente está pensado para GitHub.com. Si prefieres probar el ejemplo con GitHub AE, debes reemplazar
https://api.github.com
porhttps://HOSTNAME/api/v3
y reemplazarHOSTNAME
por el nombre de host de GitHub AE. También debes reemplazaroctocat/Spoon-Knife
por un repositorio en GitHub AE. - Si quieres realizar solicitudes de API desde la línea de comandos, GitHub recomienda usar GitHub CLI, lo que simplifica la autenticación y las solicitudes. Para obtener más información sobre cómo empezar a trabajar con la API de REST con GitHub CLI, consulta la versión de GitHub CLI de este artículo.
-
Instala
curl
si aún no está instalado en la máquina. Para comprobar sicurl
está instalado, ejecutacurl --version
en la línea de comandos. Si la salida es información sobre la versión decurl
, se instala. Si recibes un mensaje similar acommand not found: curl
, debes descargar e instalarcurl
. Para más información, consulta la página de descarga del proyecto curl. -
Creación de un token de acceso. Por ejemplo, cree un personal access token o un token de acceso de usuario GitHub App. Para más información, consulta "Creación de un personal access token" o "Identificación y autorización de usuarios para aplicaciones de GitHub".
Advertencia: trata el token de acceso igual que una contraseña.
También puedes usar GitHub CLI en lugar de
curl
. GitHub CLI se encargará de la autenticación. Para obtener más información, consulta la versión de GitHub CLI de esta página.Si estas opciones no son posibles, considera el uso de otro servicio de CLI para almacenar el token de forma segura.
-
Usa el comando
curl
para realizar la solicitud. Pasa el token en un encabezadoAuthorization
. ReemplaceYOUR-TOKEN
por su token.curl --request GET \ --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer YOUR-TOKEN"
Nota: En la mayoría de los casos, puedes usar
Authorization: Bearer
oAuthorization: token
para pasar un token. Sin embargo, si vas a pasar un token web JSON (JWT), debes usarAuthorization: Bearer
.
Uso de comandos curl
en GitHub Actions
También puedes utilizar comandos curl
en tus flujos de trabajo de GitHub Actions.
GitHub recomienda autenticarse con el GITHUB_TOKEN
integrado en lugar de crear un token. Si esto no es posible, almacena el token como secreto y reemplaza GITHUB_TOKEN
en el ejemplo siguiente por el nombre del secreto. Para obtener más información sobre GITHUB_TOKEN
, consulta "Autenticación automática de tokens". Para obtener más información sobre secretos, consulte "Using secrets in GitHub Actions".
Nota: Los flujos de trabajo de ejemplo siguientes están pensados para GitHub.com. Si prefieres probar los ejemplos con GitHub AE, ten en cuenta las siguientes diferencias.
- Debe reemplazar
https://api.github.com
porhttps://HOSTNAME/api/v3
y reemplazarHOSTNAME
por el nombre de host de GitHub AE. - Debes reemplazar por
octocat/Spoon-Knife
un repositorio en GitHub AE.
on:
workflow_dispatch:
jobs:
use_api:
runs-on: ubuntu-latest
permissions:
issues: read
steps:
- env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer $GH_TOKEN"
Si está autenticando con un GitHub App, puedes crear un token de acceso de instalación en el flujo de trabajo:
-
Almacena la ID de tu GitHub App como un secreto. En el flujo de trabajo siguiente, reemplaza
APP_ID
por el nombre del secreto. Puedes encontrar tu ID de app en la página de ajustes de tu app o mediante la API de la misma. Para obtener más información, vea «Aplicaciones de GitHub». Para obtener más información sobre secretos, consulte "Using secrets in GitHub Actions". -
Generar una llave privada para tu app. Almacena el contenido del archivo resultante como un secreto. (Almacena todo el contenido del archivo, incluido el contenido de
-----BEGIN RSA PRIVATE KEY-----
y-----END RSA PRIVATE KEY-----
). En el siguiente ejemplo, reemplazaAPP_PEM
por el nombre del secreto. Para obtener más información, vea «Administración de claves privadas para aplicaciones de GitHub». -
Agrega un paso para generar un token y use ese token en lugar de
GITHUB_TOKEN
. Ten en cuenta que este token expirará después de 60 minutos. Por ejemplo:on: workflow_dispatch: jobs: use_api: runs-on: ubuntu-latest steps: - name: Generate token id: generate_token uses: actions/create-github-app-token@v1 with: app_id: ${{ secrets.APP_ID }} private_key: ${{ secrets.APP_PEM }} - name: Use API env: GH_TOKEN: ${{ steps.generate_token.outputs.token }} run: | curl --request GET \ --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer $GH_TOKEN"
Pasos siguientes
Para obtener más información, consulta "Introducción a la API de REST".