Nota: Los tokens de usuario con vigencia determinada actualmente son una característica opcional y están sujetos a cambios. Para decidir unirse a o salir de la característica de vigencia determinada de los tokens de usuario a servidor, consulta la sección "Activar las características opcionales para las apps". Para obtener más información, consulta la sección "Tokens de acceso con caducidad de usuario a servidor para las GitHub Apps".
Cuando tu GitHub App actúe en nombre de un usuario, ésta realiza solicitudes de usuario a servidor. Estas solicitudes deben autorizarse con un token de acceso de usuario. Las solicitudes de usuario a servidor incluyen el solicitar datos para un usuario, como el determinar qué repositorios mostrar a un usuario en particular. Estas solicitudes también incluyen las acciones que activa un usuario, como ejecutar una compilación.
Para mantener más seguros los tokens de acceso de usuario a servidor, puedes utilizar tokens de acceso que caducarán después de 8 horas, y un token de actualización que se puede intercambiar por un token de acceso nuevo. Para obtener más información, consulta la sección "Actualizar los tokens de acceso de usuario a servidor".
Identificar usuarios en tu sitio
Para autorizar a los usuarios para las apps estándar que se ejecutan en el buscador, utiliza el flujo de aplicaciones web.
Para autorizar a los usuarios para apps sin interfaz gráfica sin acceso directo al buscador, tales como las herramientas de CLI o administradores de credenciales de Git, utiliza el flujo del dispositivo. El flujo de dispositivos utiliza el Otorgamiento de Autorizción de Dispositivos de OAuth 2.0.
Flujo de aplicaciones Web
Al utilizar el flujo de aplicaciones web, el proceso para identificar a los usuarios en tu sitio es:
- Se redirecciona a los usuarios para solicitar su identidad de GitHub
- GitHub redirecciona a los usuarios de vuelta a tu sitio
- Tu GitHub App accede a la API con el token de acceso del usuario
Si seleccionas Solicitar la autorización del usuario (OAuth) durante la instalación cuando crees o modifiques tu app, el paso 1 se completará durante la instalación de la misma. Para obtener más información, consulta la sección "Autorizar usuarios durante la instalación".
1. Solicita la identidad de un usuario de GitHub
Dirige al usuario a la siguiente URL en su buscador:
GET http(s)://[hostname]/login/oauth/authorize
Cuando tu GitHub App especifica un parámetro de login, solicita a los usuarios con una cuenta específica que pueden utilizar para registrarse y autorizar tu app.
Parámetros
| Nombre | Tipo | Descripción |
|---|---|---|
client_id | secuencia | Requerido. La ID de cliente para tu GitHub App. Puedes encontrarla en los Ajustes de tu GitHub App cuando selecciones tu app. Nota: La ID de app y de cliente no son las mismas y no son intercambiables. |
redirect_uri | secuencia | La URL en tu aplicación a donde se enviará a los usuarios después de la autorización. Esto debe ser una coincidencia exacta con una de las URL que proporcionaste como URL de rellamado cuando configuraste tu GitHub App y no puede contener ningún parámetro adicional. |
state | secuencia | Este deberá contener una secuencia aleatoria para dar protección contra los ataques de falsificación y podría contener cualquier otros datos arbitrarios. |
login | secuencia | Sugiere una cuenta específica para utilizar para registrarse y autorizar la app. |
allow_signup | secuencia | Ya sea que se ofrezca no una opción para que los usuarios autenticados se registren para GitHub durante el flujo de OAuth. la opción predeterminada es true. Utiliza false cuando una política prohíba los registros. |
Nota: No necesitas proporcionar alcances en tu solicitud de autorización. A diferencia de la OAuth trandicional, el token de autorizción se limita a los permisos asociados con tu GitHub App y a aquellos del usuario.
2. GitHub redirecciona a los usuarios de vuelta a tu sitio
Si el usuario acepta tu solicitud, GitHub te redirecciona de regreso a tu sitio con un code temporal en un parámetro de código así como con el estado que proporcionaste en el paso anterior en el parámetro state. Si los estados no coinciden significa que un tercero creó la solicitud y que se debe anular el proceso.
Nota: Si seleccionas Solicitar la autorización del usuario (OAuth) durante la instalación cuando creas o modificas tu app, GitHub regreará un code temporal que necesitarás intercambiar por un token de acceso. El parámetro state no se regresa cuando GitHub inicia el flujo de OAuth durante la instalación de la app.
Intercambia este code por un token de acceso. Cuando se habilita el vencimiento de tokens, el token de acceso vence en 8 horas y el token de actualización en 6 meses. Cada que actualizas el token, obtienes un nuevo token de actualización. Para obtener más información, consulta la sección "Actualziar los tokens de acceso usuario-servidor".
Los tokens de usuario con vigencia determinada son una característica opcional actualmente y están sujetos a cambios. Para decidir participar en la característica de vencimiento de tokens usuario-servidor, consulta la sección "Activar las características opcionales para las apps".
Haz una solicitud a la siguiente terminal para recibir un token de acceso:
POST http(s)://[hostname]/login/oauth/access_token
Parámetros
| Nombre | Tipo | Descripción |
|---|---|---|
client_id | secuencia | Requerido. La ID de cliente para tu GitHub App. |
client_secret | secuencia | Requerido. El secreto de cliente para tu GitHub App. |
código | secuencia | Requerido. El código que recibiste como respuesta al Paso 1. |
redirect_uri | secuencia | La URL en tu aplicación a donde se enviará a los usuarios después de la autorización. Esto debe ser una coincidencia exacta con una de las URL que proporcionaste como URL de rellamado cuando configuraste tu GitHub App y no puede contener ningún parámetro adicional. |
state | secuencia | La secuencia aleatoria indescifrable que proporcionaste en el Paso 1. |
Respuesta
Predeterminadametne, la respuesta lleva el siguiente formato. Los parámetros de respuesta expires_in, refresh_token, y refresh_token_expires_in solo se devuelven cuando habilitas la vigencia determinada para los tokens de acceso de usuario a servidor.
{
"access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a",
"expires_in": 28800,
"refresh_token": "r1.c1b4a2e77838347a7e420ce178f2e7c6912e1692",
"refresh_token_expires_in": 15811200,
"scope": "",
"token_type": "bearer"
}
3. Tu GitHub App accede a la API con el token de acceso del usuario
El token de acceso del usuario permite que la GitHub App haga solicitudes a la API a nombre del usuario.
Authorization: token OAUTH-TOKEN
GET http(s)://[hostname]/api/v3/user
Por ejemplo, en curl, puedes configurar el encabezado de autorización de la siguiente manera:
curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/userFlujo de dispositivos
Nota: El flujo de dispositivos se encuentra en un beta público y está sujeto a cambios.
Este flujo de dispositivos te permite autorizar usuarios para una app sin encabezado, tal como una herramienta de CLI o un administrador de credenciales de Git.
Para obtener más información sobre cómo autorizar usuarios utilizando el flujo de dispositivos, consulta la sección "Autorizar las Apps de OAuth".
Revisar a qué recursos de instalación puede acceder un usuario
Ya que tengas un token de OAuth para un usuario, puedes revisar a qué instalaciones puede acceder.
Authorization: token OAUTH-TOKEN
GET /user/installations
También puedes verificar qué repositorios se encuentran accesibles para un usuario para una instalación.
Authorization: token OAUTH-TOKEN
GET /user/installations/:installation_id/repositories
Puedes encontrar más detalles en: Listar instalaciones de app accesibles para el token de acceso del usuario y Listar repositorios accesibles para el token de acceso del usuario.
Gestionar una autorización revocada a una GitHub App
Si un usuario revoca su autorización de una GitHub App, dicha app recibirá el webhook github_app_authorization predeterminadamente. Las GitHub Apps no pueden desuscribirse de este evento. Cualquiera puede revocar su autorización a una GitHub App desde su página de ajustes de cuenta de GitHub. Revocar la autorización de una GitHub App no la desinstalará. Debes programar tu GitHub App para que cuando reciba su webhook deje de llamar a la API en nombre de la persona que revocó el token. Si tu GitHub App sigue utilizando un token de acceso revocado, esta recibirá el error 401 Bad Credentials.
Permisos a nivel de usuario
Puedes agregar permisos a nivel de usuario a tu GitHub App para acceder a los recursos del usuario, tales como correos electrónicos del usuario, los cuales otorgan los usuarios independientes como parte del flujo de autorización del usuario. Los permisos a nivel de usuario difieren de los permisos a nivel de organización y de repositorio, los cuales se otorgan en el momento de la instalación en una cuenta personal o de organización.
Puedes seleccionar los permisos a nivel de usuario desde dentro de la configuración de tu GitHub App en la sección de Permisos de usuario de la página de Permisos & webhooks. Para obtener más información sobre seleccionar permisos, consulta la sección Editar los permisos de una GitHub App".
Cuando un usuario instala tu app en su cuenta, el aviso de instalación listará los permisos a nivel de usuario que tu app está solicitando y explicará que la app puede pedir estos permisos a los usuarios independientes.
Ya que los permisos a nivel de usuario se otorgan individualmente, puedes agregarlos a tu app existente sin solicitar que los usuarios los mejoren. Sin embargo, necesitarás enviar usuarios existentes a través del flujo de autorización de usuarios para autorizar los permisos nuevos y obtener un token nuevo de usuario a servidor para estas solicitudes.
Solicitudes de usuario a servidor
Mientras que la mayoría de tu interacción con la API deberá darse utilizando tus tokens de acceso a la instalación de servidor a servidor, ciertas terminales te permiten llevar a cabo acciones a través de la API utilizando un token de acceso. Tu app puede hacer las siguientes solicitudes utilizando terminales de GraphQL o de REST.
Terminales compatibles
Ejecuciones de Verificación
- Crear una ejecución de verificación
- Obtener una ejecución de verificación
- Actualizar una ejecución de verificación
- Listar las anotaciones de una ejecución de verificación
- Listar las ejecuciones de verificación en un conjunto de verificaciones
- Listar las ejecuciones de verificación para una referencia de Git
Conjuntos de Verificaciones
- Crear un conjunto de verificaciones
- Obtener un conjunto de verificaciones
- Solicitar un conjunto de verificaciones
- Actualizar las preferencias del repositorio para los conjuntos de verificaciones
- Listar conjuntos de verificaciones para una referencia de Git
Códigos de Conducta
Estados de Despliegue
Implementaciones
Eventos
Fuentes
Blobs de Git
Confirmaciones de Git
Referencias de Git
- Crear una referencia
- Obtener una referencia
- Lista las referencias coincidentes
- Actualizar una referencia
- Borrar una referencia
Matrículas de Git
Árboles de Git
Plantillas de Gitignore
Instalaciones
Asignados de Informes de Problemas
Comentarios de Informes de Problemas
- Listar comentarios del informe de problemas
- Crear un comentario del informe de problemas
- Listar cometnarios del informe de problemas para un repositorio
- Obtener un comentario de un informe de problemas
- Actualizar un comentario de un informe de problemas
- Borrar un comentario de un informe de problemas
Eventos de Informe de Problemas
Línea de tiempo del Informe de Problemas
Problemas
- Listar informes de problemas asignados al usuario autenticado
- Listar asignados
- Revisar si se puede asignar un usuario
- Listar informes de problemas del repositorio
- Crear un informe de problemas
- Obtener un informe de problemas
- Actualizar un informe de problemas
- Bloquear un informe de problemas
- Desbloquear un informe de problemas
Etiquetas
- Listar las etiquetas para un informe de problemas
- Agregar etiquetas a un informe de problemas
- Configurar eitquetas para un informe de problemas
- Eliminar todas las etiquetas de un informe de problemas
- Eliminar una etiqueta de un informe de problemas
- Listar etiquetas para un repositorio
- Crear una etiqueta
- Obtener una etiqueta
- Actualizar una etiqueta
- Borrar una etiqueta
- Obtener etiquetas para cada informe de problemas en un hito
Licencias
Markdown
Meta
Hitos
Ganchos de organización
- Listar los webhooks de la organización
- Crear un webhook para una organización
- Obtener un webhook de una organización
- Actualizar el webhook de una organización
- Borrar el webhook de una organización
- Hacer ping al webhook de una organización
Miembros de la Organización
- Listar a los miembros de la organización
- Verificar la membrecía de organización de un usuario
- Eliminar a un miembro de una organización
- Obtener la membrecía de organización para un usuario
- Configurar una mebrecía de organización para un usuario
- Eliminar la membrecía de organización de un usuario
- Listar los miembros de una organización pública
- Verificar la membrecía de una organización pública de un usuario
- Configurar la membrecía de una organización pública para el usuario autenticado
- Eliminar la membrecía de una organizción pública del usuario autenticado
Colaboradores Externos de una Organización
- Listar los colaboradores externos de una organización
- Convertir a un miembro de la organización en colaborador externo
- Eliminar a un colaborador externo de la organización
Ganchos de Pre-recepción de la Organización
- Listar los ganchos de pre-recepción de una organización
- Obtener los ganchos de pre-recepción de una organización
- Actualizar el requerir los ganchos de pre-recepción para una organización
- Eliminar el requerir los ganchos de pre-recepción para una organización
Poyectos de Equipo de una Organización
- Listar los proyectos de equipo
- Verificar los permisos del equipo para un proyecto
- Agregar o actualizar los permisos de un proyecto de equipo
- Eliminar a un proyecto de un equipo
Repositorios de Equipo de la Organización
- Listar los repositorios de equipo
- Verificar los permisos de un equipo para un repositorio
- Agregar o actualizar los permisos de un repositorio de equipo
- Eliminar a un repositorio de un equipo
Equipos de la Organización
Organizaciones
- Listar organizaciones
- Obtener una organización
- Actualizar una organización
- Listar membrecías de organización para el usuario autenticado
- Obtener la membrecía de organización para el usuario autenticado
- Actualizar la membrecía de una organización para el usuario autenticado
- Listar las organizaciones para el usuario autenticado
- Listar las organizaciones de un usuario
Colaboradores de Proyecto
- Listar colaboradores del proyecto
- Agregar a un colaborador del proyecto
- Eliminar a un colaborador del proyecto
- Obtener permisos del proyecto para un usuario
Proyectos
- Listar los proyectos de la organización
- Crear un proyecto en la organización
- Obtener un proyecto
- Actualizar un proyecto
- Borrar un proyecto
- Listar las columnas del proyecto
- Crear una columna de proyecto
- Obtener una columna de proyecto
- Actualizar una column de proyecto
- Borrar una columna de proyecto
- Listar las tarjetas del proyecto
- Crear una tarjeta de proyecto
- Mover una columna de proyecto
- Obtener una tarjeta de proyecto
- Actualizar una tarjeta de proyecto
- Borrar una tarjeta de proyecto
- Mover una tarjeta de proyecto
- Listar los proyectos de un repositorio
- Crear un proyecto en un repositorio
Comentarios de Extracción
- Listar comentarios de revisión en una solicitud de extracción
- Crear un comentario de revisión para una solicitud de extracción
- Listar comentarios de revisión en un repositorio
- Obtener un comentario de revisión para una solicitud de extracción
- Actualizar un comentario de revisión para una solicitud de extracción
- Borrar un comentario de revisión para una solicitud de extracción
Eventos de Revisión en Solciitudes de Extracción
- Descartar una revisión para una solicitud de extracción
- Emitir una revisión para una solicitud de extracción
Solicitudes de Revisión para Solicitudes de Extracción
- Listar a los revisores requeridos para una solicitud de extracción
- Solicitar a los revisores para una solicitud de extracción
- Eliminar a los revisores solicitados para una solicitud de extracción
Revisiones de Solicitudes de Extracción
- Listar revisores para una solicitud de extracción
- Crear revisión para una solicitud de extracción
- Obtener una revisión para una solicitud de extracción
- Actualizar una revisión para una solicitud de extracción
- Listar los comentarios para una revisión de una solicitud de extracción
Extracciones
- Listar solicitudes extracción
- Crear una solicitud de extracción
- Obtener una solicitud de extracción
- Actualizar una solicitud de extracción
- Listar las confirmaciones en una solicitud de extracción
- Listar los archivos en una solicitud de extracción
- Revisar si se ha fusionado una solicitud de extracción
- Fusionar una solicitud de extracción (Botón de Fusionar)
Reacciones
- Borra una reacción
- Listar las reacciones a un comentario de una confirmación
- Crear una reacción para el comentario de una confirmación
- Listar las reacciones de un informe de problemas
- Crear una reacción para un informe de problemas
- Listar las reacciones para el comentario de un informe de problemas
- Crear una reacción para el comentario de informe de problemas
- Listar las reacciones para el comentario de revisión de una solicitud de extracción
- Crear una reacción para un comentario de revisión de una solicitud de extracción
- Listar las reacciones para un comentario de debate de equipo
- Crear una reacción para un comentario de debate de equipo
- Listar las reaciones a un debate de equipo
- Crear una reacción para un debate de equipo
- Borrar la reacción a un comentario de una confirmación
- Borrar la reacción a un comentario
- Borrar la reacción a un comentario de una confirmación
- Borrar la reacción a un comentario de una solicitud de extracción
- Borrar la reacción a un debate de equipo
- Borrar una reacción a un comentario en un debate de equipo
Repositorios
- Listar los repositorios de una organización
- Crear un repositorio para el usuario autenticado
- Obtener un repositorio
- Actualizar un repositorio
- Borrar un repositorio
- Comparar dos confirmaciones
- Listar los colaboradores del repositorio
- Listar las bifurcaciones
- Crear una bifuración
- Listar los lenguajes de un repositorio
- Listar las matrículas de un repositorio
- Listar los equipos de un repositorio
- Transferir un repositorio
- Listar los repositorios públicos
- Listar los repositorios para el usuario autenticado
- Listar los repositorios para un usuario
- Crear un repositorio utilizando una plantilla de repositorio
Actividad del Repositorio
- Listar Stargazers
- Listar observadores
- Listar los repositorios que el usuario ha marcado con una estrella
- Verificar si el usuario autenticado ha marcado al repositorio con una estrella
- Marcar un repositorio con una estrella para el usuario autenticado
- Quitar la estrella de un repositorio para el usuario autenticado
- Listar los repositorios que el usuario está observando
Ramas de los Repositorios
- Listar ramas
- Obtener una rama
- Obtener la protección de una rama
- Actualizar la protección de una rama
- Borrar la protección de una rama
- Obtener la protección administrativa de una rama
- Configurar la protección administrativa de una rama
- Borrar la protección administrativa de una rama
- Obtener la protección de la revisión de una solicitud de extracción
- Actualizar la protección de la revisión de una solicitud de extracción
- Borrar la protección de la revisión de una solicitud de extracción
- Obtener la protección de firma de una confirmación
- Crear la protección de firma de una confirmación
- Borrar la protección de firma de una confirmación
- Obtener la protección de las verificaciones de estado
- Actualizar la protección para la verificación de estados
- Eliminar la protección de las verificaciones de estado
- Obtener todos los contextos de verificaciones de estado
- Agregar un contexto de verificación de estado
- Obtener un contexto de verificación de estado
- Eliminar los contextos de verificación de estado
- Obtener restricciones de acceso
- Borrar restricciones de acceso
- Listar a los equipos con acceso a la rama protegida
- Agregar restricciones de acceso a equipos
- Obtener restricciones de acceso a equipos
- Eliminar restricciones de acceso a equipos
- Listar las restricciones de usuario para la rama protegida
- Agregar las restricciones de acceso para los usuarios
- Configurar las restricciones de acceso para los usuarios
- Eliminar las restricciones de acceso para los usuarios
- Fusionar una rama
Colaboradores del Repositorio
- Listar los colaboradores del repositorio
- Verificar si un usuario es colaborador de un repositorio
- Agregar un colaborador de repositorio
- Eliminar a un colaborador del repositorio
- Obtener permisos del repositorio para un usuario
Comentarios de Confirmaciones de un Repositorio
- Listar los comentarios de confirmaciones en un repositorio
- Obtener un comentario de una confirmación
- Actualizar un comentario de una confirmación
- Borrar un comentario de una confirmación
- Listar los comentarios de una confirmación
- Crear un comentario de una confirmación
Confirmaciones de Repositorio
- Listar confirmaciones
- Obtener una confirmación
- Listar ramas para la confirmación principal
- Listar solicitudes de extracción asociadas con una confirmación
Comunidad del Repositorio
Contenido de los Repositorios
- Descargar un archivo de un repositorio
- Obtener el contenido de un repositorio
- Crear o actualizar los contenidos de archivo
- Borrar un archivo
- Obtener el README de un repositorio
- Obtener la licencia para un repositorio
Envíos de Evento de un Repositorio
Ganchos de Repositorio
- Listar los webhooks de un repositorio
- Crear un webhook para un repositorio
- Obtener un webhook para un repositorio
- Actualizar el webhook de un repositorio
- Borrar el webhook de un repositorio
- Hacer ping al webhook de un repositorio
- Probar el webhook de carga a un repositorio
Invitaciones a un repositorio
- Listar las invitaciones a un repositorio
- Actualizar la invitación a un repositorio
- Borrar la invitación a un repositorio
- Listar las invitaciones a un repositorio para el usuario autenticado
- Aceptar la invitación a un repositorio
- Rechazar la invitación a un repositorio
Claves de Repositorio
- Listar claves de despliegue
- Crear una clave de despliegue
- Obtener una clave de despliegue
- Borrar una clave de despiegue
Páginas de Repositorio
- Obtener un sitio de GitHub Pages
- Crear un sitio de GitHub Pages
- Actualizar la información acerca de un sitio de GitHub Pages
- Borrar un sitio de GitHub Pages
- Listar las compilaciones de GitHub Pages
- Solicitar una compilación de GitHub Pages
- Obtener una compilación de GitHub Pages
- Obtener la última compilación de pages
Ganchos de Pre-recepción de un Repositorio
- Listar los ganchos de pre-recepción para un repositorio
- Obtener un gancho de pre-recepción de un repositorio
- Actualizar el requerir ganchos de pre-recepción en un repositorio
- Eliminar el requerir ganchos de pre-recepción para un repositorio
Lanzamientos de repositorio
- Listar los lanzamientos
- Crear un lanzamiento
- Obtener un lanzamiento
- Actualizar un lanzamiento
- Borrar un lanzamiento
- Listar activos de lanzamiento
- Obtener un activo de lanzamiento
- Actualizar un activo de lanzamiento
- Borrar un activo de lanzamiento
- Obtener el lanzamiento más reciente
- Obtener un lanzamiento por nombre de matrícula
Estadísticas de Repositorio
- Obtener la actividad de confirmaciones semanal
- Obtener la actividad de confirmaciones del año pasado
- Obtener la actividad de confirmaciones de todos los colaboradores
- Obtener la cuenta semanal de confirmaciones
- Obtener la cuenta de confirmaciones por hora para cada día
Raíz
Buscar
- Buscar código
- Buscar confirmaciones
- Buscar etiquetas
- Buscar repositorios
- Buscar temas
- Buscar usuarios
Estados
- Obtener el estado combinado para una referencia específica
- Listar los estados de confirmación para una referencia
- Crear un estado de confirmación
Debates de Equipo
- Listar debates
- Crear un debate
- Obtener un debate
- Actualizar un debate
- Borrar un debate
- Listar los comentarios del debate
- Crear un comentario sobre un debate
- Obtener un comentario de un debate
- Actualizar un comentario en un debate
- Borrar un comentario de un debate
Temas
Correo Electrónico de Usuario
- Listar las direcciones de correo electrónico para el usuario autenticado
- Agregar la(s) dirección(es) de correo electrónico
- Borrar la(s) direccion(es) de correo electrónico
- Listar las direcciones de correo electrónico del usuario autenticado
Seguidores del Usuario
- Listar los seguidores de un usuario
- Listar a las personas que sigue un usuario
- Revisar si el usuario autenticado sigue a una persona
- Seguir a un usuario
- Dejar de seguri a un usuario
- Verificar si el usuario sigue a otro usuario
Utilizar Llaves Gpg
- Listar las llaves GPG para el usuario autenticado
- Crear una llave GPG para el usuario autenticado
- Obtener una llave GPG para el usuario autenticado
- Borrar una llave GPG para el usuario autenticado
- Listar las llaves GPG de un usuario
Llaves Públicas de Usuario
- Listar las llaves SSH para el usuario autenticado
- Crear una llave SSH para el usuario autenticado
- Obtener una llave SSH pública para el usuario autenticado
- Borrar una llave pública de SSH para el usuario autenticado
- Listar las llaves públicas de un usuario