Acerca de la autenticación como una instalación de GitHub App
Una vez que GitHub App se instala en una cuenta, puedes realizar la autenticación como una instalación de la aplicación para las solicitudes de API. Esto permite que la aplicación acceda a los recursos que son propiedad de esa instalación, siempre y cuando se haya concedido a la aplicación el acceso y los permisos necesarios del repositorio. Las solicitudes de API realizadas por una instalación de la aplicación se atribuyen a la aplicación. Para obtener más información sobre cómo instalar aplicaciones de GitHub, consulta "Instalación de aplicaciones de GitHub".
Por ejemplo, si quieres que tu aplicación cambie el campo Status
de una incidencia en un proyecto que pertenece a una organización denominada "octo-org", te autenticarías como la instalación de octo-org de la aplicación. La escala de tiempo del problema indicaría que la aplicación actualizó el estado.
Para realizar una solicitud de API como instalación, primero debes generar un token de acceso de instalación. A continuación, enviarás el token de acceso de instalación en el encabezado Authorization
de las solicitudes de API posteriores. También puedes usar los SDK de Octokit de GitHub, que pueden generar un token de acceso de instalación automáticamente.
Algunos puntos de conexión de la API de REST no aceptan tokens de acceso de instalación y la mayoría de los puntos de conexión de la API de REST requieren que la aplicación tenga determinados permisos para usar un punto de conexión. Para ver si un punto de conexión de la API de REST acepta tokens de acceso de instalación y para ver qué permisos son necesarios, consulte la documentación del punto de conexión.
Las instalaciones de aplicaciones también pueden usar GraphQL API. De forma similar a la API REST, la aplicación debe tener determinados permisos para acceder a objetos en GraphQL API. En el caso de las solicitudes de GraphQL, debes probar que la aplicación tiene los permisos necesarios para las consultas y mutaciones de GraphQL que deseas realizar.
También puedes usar un token de acceso de instalación para autenticarte para el acceso de Git basado en HTTP. La aplicación debe tener el permiso de repositorio "Contenido". Después, puedes usar el token de acceso de instalación como contraseña HTTP. Reemplaza TOKEN
por el token de acceso de instalación: git clone https://x-access-token:TOKEN@github.com/owner/repo.git
Las solicitudes realizadas con un token de acceso de instalación a veces se denominan solicitudes de "servidor a servidor".
Para obtener más información sobre la autenticación como una aplicación en nombre de un usuario en lugar de como una instalación de la aplicación, consulta "Autenticación con una aplicación de GitHub en nombre de un usuario".
Uso de un token de acceso de instalación para autenticarte como una instalación de la aplicación
Para autenticarte como una instalación con un token de acceso de instalación, usa primero la API REST para generar un token de acceso de instalación. A continuación, usa ese token de acceso de instalación en el encabezado Authorization
de una API REST o una solicitud de GraphQL API. El token de acceso de instalación expirará después de 1 hora.
Generación de un token de acceso de instalación
-
Genera un JSON Web Token (JWT) para la aplicación. Para más información, consulta "Generación de un JSON Web Token (JWT) para una aplicación de GitHub".
-
Consigue el identificador de la instalación con el que deseas autenticarte.
Si respondes a un evento de webhook, la carga del webhook incluirá el identificador de la instalación.
También puedes usar la API REST para buscar el identificador de una instalación de la aplicación. Por ejemplo, puedes obtener un identificador de instalación con los puntos de conexión
GET /users/{username}/installation
,GET /repos/{owner}/{repo}/installation
,GET /orgs/{org}/installation
oGET /app/installations
. Para obtener más información, consulta "Puntos de conexión de la API de REST para GitHub Apps".Puedes encontrar el identificador de aplicación en la página de configuración de la aplicación. El id. de la aplicación es diferente del id. de cliente. Para más información sobre cómo desplazarte a la página de configuración en tu GitHub App, consulta “Modificación del registro de una instancia de GitHub App”.
-
Envía una solicitud de API REST
POST
a/app/installations/INSTALLATION_ID/access_tokens
. Incluye JSON Web Token en el encabezadoAuthorization
de la solicitud. ReemplazaINSTALLATION_ID
por el identificador de la instalación con el que deseas autenticarte.Por ejemplo, envía esta solicitud curl. Reemplaza
INSTALLATION_ID
por el identificador de la instalación yJWT
por JSON Web Token:curl --request POST \ --url "https://api.github.com/app/installations/INSTALLATION_ID/access_tokens" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer JWT" \ --header "X-GitHub-Api-Version: 2022-11-28"
Opcionalmente, puedes utilizar los parámetros de cuerpo
repositories
orepository_ids
para especificar repositorios individuales a los que puede acceder el token de acceso a la instalación. Si no usasrepositories
orepository_ids
para conceder acceso a repositorios específicos, el token de acceso a la instalación tendrá acceso a todos los repositorios a los que se concedió acceso a la instalación. Al token de acceso de instalación no se le puede conceder acceso a los repositorios a los que la instalación no tuvo acceso. Es posible enumerar hasta 500 repositorios.Opcionalmente, usa el parámetro de cuerpo
permissions
para especificar los permisos que debe tener el token de acceso de instalación. Si no se especificapermissions
, el token de acceso de instalación tendrá todos los permisos concedidos a la aplicación. No se pueden conceder al token de acceso a la instalación permisos que la aplicación no tenía concedidos.Al usar los parámetros
permissions
para reducir el acceso del token, se aumenta la complejidad de dicho token debido al número de permisos de la solicitud y al número de repositorios a los que tendrá acceso. Si la complejidad es demasiado grande, se recibirá un mensaje de error que indica el número máximo de repositorios que se pueden admitir. En este caso, se deben solicitar menos permisos con el parámetropermissions
, utilizar el parámetrorepositories
orepository_ids
para solicitar menos repositorios, o bien instalar la aplicación en repositoriosall
de su organización.La respuesta incluirá un token de acceso de instalación, la hora en que expira el token, los permisos que tiene el token y los repositorios a los que puede acceder el token. El token de acceso de instalación expirará después de 1 hora.
Para obtener más información sobre este punto de conexión, consulta "Puntos de conexión de la API de REST para GitHub Apps".
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
.
Autenticación con un token de acceso de instalación
Para autenticarte con un token de acceso de instalación, inclúyelo en el encabezado Authorization
de la solicitud de API. El token de acceso funcionará con GraphQL API y la API REST.
La aplicación debe tener los permisos necesarios para usar el punto de conexión. Para obtener más información, vea «Elección de permisos para una aplicación de GitHub».
En el ejemplo siguiente, reemplaza INSTALLATION_ACCESS_TOKEN
por un token de acceso de instalación:
curl --request GET \
--url "https://api.github.com/meta" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer INSTALLATION_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"
Uso del SDK de Octokit.js para autenticarte como una instalación de la aplicación
Puedes usar el SDK de Octokit.js de GitHub para autenticarte como una instalación de la aplicación. Una ventaja de usar el SDK para autenticarte es que no tienes que generar un JSON Web Token (JWT) personalmente. Además, el SDK se encargará de regenerar un token de acceso a la instalación para que no tengas que preocuparte por la expiración de una hora.
Debes instalar e importar octokit
para usar la biblioteca de Octokit.js. En el ejemplo siguiente se usan instrucciones import de acuerdo con ES6. Para obtener más información sobre los diferentes métodos de instalación e importación, consulta la sección Uso del archivo README de Octokit.js.
Uso de Octokit.js para autenticarte con un identificador de instalación
-
Obtén el identificador de GitHub App. Puedes encontrar el id. de la aplicación en la página de configuración de la GitHub App. Para más información sobre cómo desplazarte a la página de configuración en tu GitHub App, consulta "Modificación del registro de una instancia de GitHub App".
-
Genere una clave privada. Para más información, consulta "Administración de claves privadas para aplicaciones de GitHub".
-
Consigue el identificador de la instalación con el que deseas autenticarte.
Si respondes a un evento de webhook, la carga del webhook incluirá el identificador de la instalación.
También puedes usar la API REST para buscar el identificador de una instalación de la aplicación. Por ejemplo, puedes obtener un identificador de instalación con los puntos de conexión
GET /users/{username}/installation
,GET /repos/{owner}/{repo}/installation
,GET /orgs/{org}/installation
oGET /app/installations
. Para más información, consulta "Puntos de conexión de la API de REST para GitHub Apps". -
Importa
App
desdeoctokit
. Cree una nueva instancia deApp
. En el ejemplo siguiente, reemplazaAPP_ID
por una referencia al identificador de la aplicación. ReemplazaPRIVATE_KEY
por una referencia a la clave privada de la aplicación.JavaScript import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, });
import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, });
-
Usa el método
getInstallationOctokit
para crear una instancia autenticada deoctokit
. En el ejemplo siguiente, reemplazaINSTALLATION_ID
por el identificador de la instalación de la aplicación en nombre de la cual quieras autenticarte.JavaScript const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
-
Usa un método
octokit
para realizar una solicitud a la API.La aplicación debe tener los permisos necesarios para usar el punto de conexión. Para obtener más información, vea «Elección de permisos para una aplicación de GitHub».
Por ejemplo, para realizar una solicitud a GraphQL API:
JavaScript await octokit.graphql(` query { viewer { login } } `)
await octokit.graphql(` query { viewer { login } } `)
Por ejemplo, para realizar una solicitud a la API REST:
JavaScript await octokit.request("GET /meta")
await octokit.request("GET /meta")
Uso de Octokit.js para autenticarte en respuesta a un evento de webhook
El SDK de Octokit.js también pasa una instancia octokit
autenticada previamente a los controladores de eventos de webhook.
-
Obtén el identificador de GitHub App. Puedes encontrar el id. de la aplicación en la página de configuración de la GitHub App. Para más información sobre cómo desplazarte a la página de configuración en tu GitHub App, consulta "Modificación del registro de una instancia de GitHub App".
-
Genere una clave privada. Para más información, consulta "Administración de claves privadas para aplicaciones de GitHub".
-
Consigue el secreto de webhook que especificaste en la configuración de la aplicación. Para más información sobre las cargas útiles de webhooks, consulta "Uso de webhooks con aplicaciones de GitHub".
-
Importa
App
desdeoctokit
. Cree una nueva instancia deApp
. En el ejemplo siguiente, reemplazaAPP_ID
por una referencia al identificador de la aplicación. ReemplazaPRIVATE_KEY
por una referencia a la clave privada de la aplicación. ReemplazaWEBHOOK_SECRET
por el secreto de webhook de la aplicación.JavaScript import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, webhooks: { WEBHOOK_SECRET }, });
import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, webhooks: { WEBHOOK_SECRET }, });
-
Usa un método
app.webhooks.*
para controlar eventos de webhook. Para obtener más información, consulta la sección Webhooks del LÉAME de Octokit.js. Por ejemplo, para crear un comentario sobre un problema cuando se abre la incidencia:app.webhooks.on("issues.opened", ({ octokit, payload }) => { await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", { owner: payload.repository.owner.login, repo: payload.repository.name, issue_number: payload.issue.number, body: `This is a bot post in response to this issue being opened.`, headers: { "x-github-api-version": "2022-11-28", }, } ) });