Skip to main content
Publicamos actualizaciones para la documentación con frecuencia y es posible que aún se esté traduciendo esta página. Para obtener la información más reciente, consulta la documentación en inglés.

Inicio rápido para la APi de REST GitHub

Obtén información sobre cómo empezar con la API de REST de GitHub.

En este artículo se describe cómo empezar a usar la API REST de GitHub mediante GitHub CLI, JavaScript o curl. Para obtener más información, consulta "Introducción a la API de 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 Enterprise Server, debes reemplazar octocat/Spoon-Knife por un repositorio en tu instancia. Como alternativa, vuelve a ejecutar el comando gh auth login para autenticarte en GitHub.com en lugar de tu instancia.

  1. Instala GitHub CLI si aún no lo has hecho. A fin de obtener instrucciones de instalación, consulta el repositorio de GitHub CLI.

  2. Usa el subcomando auth login para autenticarte en GitHub CLI. Para obtener más información, consulta la documentación de auth loginGitHub CLI.

    gh auth login
  3. Usa el subcomando api para realizar la solicitud de API. Para obtener más información, consulta la documentación de apiGitHub 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, consulta "Uso de la CLI de GitHub en 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 el GITHUB_TOKEN, consulta "Autenticación de token automática". Para más información sobre los secretos, vea "Secretos cifrados".

Nota: Los flujos de trabajo de ejemplo siguientes están pensados para GitHub.com. Si prefieres probar los ejemplos con GitHub Enterprise Server, debes reemplazar octocat/Spoon-Knife por un repositorio en GitHub Enterprise Server.

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:

  1. 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 obtener más información, consulta "Aplicaciones" en la documentación de la API de REST. Para más información sobre los secretos, vea "Secretos cifrados".

  2. 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, reemplaza APP_PEM por el nombre del secreto. Para más información, vea "Autenticación con GitHub Apps".

  3. 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:

    # Este flujo de trabajo usa acciones que no GitHub no certifica.
    # Estas las proporcionan entidades terceras y las gobiernan
    # condiciones de servicio, políticas de privacidad y documentación de soporte
    # en línea.
    
    on:
      workflow_dispatch:
    jobs:
      track_pr:
        runs-on: ubuntu-latest
        steps:
          - name: Generate token
            id: generate_token
            uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0
            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 Enterprise Server, debes reemplazar octocat/Spoon-Knife por un repositorio en tu instancia. Como alternativa, puedes crear una nueva instancia de Octokit sin especificar baseURL.

  1. Creación de un token de acceso. Por ejemplo, crea un personal access token o un token de acceso de usuario a servidor 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 la posibilidad de usar otro servicio como la CLI de 1Password para almacenar el token de forma segura.

  2. Instalar octokit. Por ejemplo, npm install octokit. Para ver otras formas de instalar o cargar octokit, consulta el archivo README de Octokit.js.

  3. Importaroctokit en tu script. Por ejemplo, import { Octokit } from "octokit";. Para obtener otras formas de importar octokit, consulta el archivo README de Octokit.js.

  4. Crea una instancia de Octokit con tu token. Reemplace YOUR-TOKEN por su token.

    const octokit = new Octokit({
      auth: 'YOUR-TOKEN'
    });
    
  5. 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 es GET, la ruta de acceso es /repos/{owner}/{repo}/issues y los parámetros son owner: "octocat" y repo: "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 más información, vea "Sintaxis de 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 el GITHUB_TOKEN, consulta "Autenticación de token automática". Para más información sobre los secretos, vea "Secretos cifrados".

Nota: El ejemplo siguiente está pensado para GitHub.com. Si prefieres probar el ejemplo con GitHub Enterprise Server, debes reemplazar octocat/Spoon-Knife por un repositorio en tu instancia. Como alternativa, puedes crear una nueva instancia de Octokit sin especificar baseURL.

Observa el siguiente flujo de trabajo de ejemplo:

  1. Comprueba el contenido del repositorio
  2. Configura Node.js
  3. Instala octokit
  4. Almacena el valor de GITHUB_TOKEN como una variable de entorno denominada TOKEN y ejecuta .github/actions-scripts/use-the-api.mjs, que puede tener acceso a esa variable de entorno como process.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@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        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:

  1. 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, consulte "Aplicaciones". Para más información sobre los secretos, vea "Secretos cifrados".

  2. 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, reemplaza APP_PEM por el nombre del secreto. Para más información, vea "Autenticación con GitHub Apps".

  3. 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:

    # Este flujo de trabajo usa acciones que no GitHub no certifica.
    # Estas las proporcionan entidades terceras y las gobiernan
    # condiciones de servicio, políticas de privacidad y documentación de soporte
    # en línea.
    
    on:
      workflow_dispatch:
    jobs:
      use_api_via_script:
        runs-on: ubuntu-latest
        steps:
          - name: Check out repo content
            uses: actions/checkout@v3
    
          - name: Setup Node
            uses: actions/setup-node@v3
            with:
              node-version: '16.17.0'
              cache: npm
    
          - name: Install dependencies
            run: npm install octokit
    
          - name: Generate token
            id: generate_token
            uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0
            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 Enterprise Server, debes reemplazar https://api.github.com por http(s)://HOSTNAME/api/v3 y reemplazar HOSTNAME por el nombre de host de your GitHub Enterprise Server instance. También debes reemplazar octocat/Spoon-Knife por un repositorio en GitHub Enterprise Server.
  • 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.
  1. Instala curl si aún no está instalado en la máquina. Para comprobar si curl está instalado, ejecuta curl --version en la línea de comandos. Si la salida es información sobre la versión de curl, se instala. Si recibes un mensaje similar a command not found: curl, debes descargar e instalar curl. Para más información, consulta la página de descarga del proyecto curl.

  2. Creación de un token de acceso. Por ejemplo, crea un personal access token o un token de acceso de usuario a servidor 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 la posibilidad de usar otro servicio como la CLI de 1Password para almacenar el token de forma segura.

  3. Usa el comando curl para realizar la solicitud. Pasa el token en un encabezado Authorization. Reemplace YOUR-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 o Authorization: token para pasar un token. Sin embargo, si vas a pasar un token web JSON (JWT), debes usar Authorization: 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 el GITHUB_TOKEN, consulta "Autenticación de token automática". Para más información sobre los secretos, vea "Secretos cifrados".

Nota: Los flujos de trabajo de ejemplo siguientes están pensados para GitHub.com. Si prefieres probar los ejemplos con GitHub Enterprise Server, ten en cuenta las siguientes diferencias.

  • Debe reemplazar https://api.github.com por http(s)://HOSTNAME/api/v3 y reemplazar HOSTNAME por el nombre de host de your GitHub Enterprise Server instance.
  • Debes reemplazar por octocat/Spoon-Knife un repositorio en GitHub Enterprise Server.
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:

  1. 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, consulte "Aplicaciones". Para más información sobre los secretos, vea "Secretos cifrados".

  2. 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, reemplaza APP_PEM por el nombre del secreto. Para más información, vea "Autenticación con GitHub Apps".

  3. 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:

    # Este flujo de trabajo usa acciones que no GitHub no certifica.
    # Estas las proporcionan entidades terceras y las gobiernan
    # condiciones de servicio, políticas de privacidad y documentación de soporte
    # en línea.
    
    on:
      workflow_dispatch:
    jobs:
      use_api:
        runs-on: ubuntu-latest
        steps:
          - name: Generate token
            id: generate_token
            uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0
            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".