Acerca de los permisos de las GitHub App
De manera predeterminada, las GitHub Apps no tiene permisos. Al registrar una instancia de GitHub App, puedes seleccionar permisos para la aplicación. Los permisos que selecciones determinan qué puede hacer la aplicación con las API de GitHub y a qué webhooks puede suscribirse la aplicación. Debes seleccionar los permisos mínimos necesarios para la aplicación.
Si bien las GitHub Apps no tienen permisos de manera predeterminada, sí tienen permisos implícitos para leer recursos públicos cuando actúan en nombre de un usuario. Cuando un usuario autoriza que la aplicación actúe en su nombre, la GitHub App puede usar el token de acceso de usuario resultante para hacer solicitudes a la API REST y la Graph API para leer recursos públicos. Para más información sobre cómo actuar en nombre de un usuario, consulta Autenticación con una aplicación de GitHub en nombre de un usuario.
Los permisos de aplicación se clasifican como permisos de repositorio, organización o cuenta. Los permisos de repositorio permiten a la aplicación acceder a los recursos relacionados con los repositorios que pertenecen a la cuenta donde está instalada la aplicación. Los permisos de la organización permiten que la aplicación acceda a los recursos relacionados con la organización donde está instalada la aplicación, si está instalada en una cuenta de la organización. Los permisos de cuenta permiten que la aplicación acceda a los recursos relacionados con un usuario si el usuario también ha autorizado la aplicación. Para obtener más información sobre la autorización de usuarios de aplicaciones, consulta Autenticación con una aplicación de GitHub en nombre de un usuario.
Cuando un usuario instala una aplicación en su cuenta u organización, ve y concede los permisos de repositorio y organización que solicitó la aplicación. También verá una lista de permisos de usuario que la aplicación puede solicitar para usuarios individuales. Cuando un usuario autoriza una aplicación para que actúe en su nombre, ve y concede los permisos de usuario que la aplicación ha solicitado.
El éxito de una solicitud de API con un token de acceso de usuario depende de los permisos del usuario, así como de los permisos de la aplicación. Por ejemplo, si se ha concedido permiso a la aplicación para escribir el contenido de un repositorio, pero el usuario solo puede leerlo, el token de acceso de usuario solo puede leer el contenido. El éxito de una solicitud de API con un token de acceso de instalación solo depende de los permisos de la aplicación.
Puede modificar los permisos de la aplicación en cualquier momento. Al modificar los permisos, se pedirá al propietario de cada cuenta en la que se instaló la aplicación que apruebe los nuevos permisos. Si el propietario de la cuenta no aprueba los nuevos permisos, su instalación seguirá usando los permisos antiguos.
Algunos webhooks y el acceso a la API requieren permisos de "administración". Si la aplicación requiere permisos de "Administración", considera la posibilidad de explicar este requisito en la página principal de la aplicación. Esto ayudará a los usuarios a comprender por qué la aplicación necesita un permiso de alto nivel.
Para más información sobre la especificación de permisos durante el registro de GitHub App, consulta Registro de una instancia de GitHub App. Para más información sobre los permisos de nivel de organización, consulta Modificación del registro de una instancia de GitHub App.
Elección de permisos para el acceso de webhook
La documentación del webhook indica si cada webhook está disponible para GitHub Apps. Para cada webhook al que quieras suscribirte, consulta la documentación del webhook para ver qué permisos necesita GitHub App para suscribirse a ese webhook. Para más información, consulta Eventos y cargas de webhook.
Por ejemplo, si quieres que la aplicación se suscriba a eventos de team, la aplicación debe tener el permiso de organización "Miembros".
En la página de registro de GitHub App, los eventos de webhook disponibles cambiarán a medida que cambies los permisos de la aplicación. Si no seleccionaste suficientes permisos para tu instancia de GitHub App para suscribirte a un evento, este no aparecerá como opción en la página de registro de la aplicación.
Elección de permisos para el acceso a la API REST
La documentación de referencia de la API de REST para cada punto de conexión indica si el punto de conexión funciona con GitHub Apps e indica qué permisos se requieren para que la aplicación use el punto de conexión. Algunos puntos de conexión pueden requerir varios permisos y algunos puntos de conexión pueden requerir uno de varios permisos. Para obtener información general sobre los puntos de conexión de la API REST a los que una GitHub Apps puede acceder con cada permiso, consulta Permisos que requieren las Github Apps.
Por ejemplo, para usar el punto de conexión GET /orgs/{org}/dependabot/secrets, la aplicación debe tener al menos permiso de nivel de lectura para el permiso "organization dependabot secrets".
Si la aplicación realiza una solicitud de API REST con permisos insuficientes, la API devolverá una respuesta 403.
Para ayudarle a elegir los permisos correctos, recibirá el encabezado X-Accepted-GitHub-Permissions en la respuesta de la API de REST. El encabezado le indicará qué permisos son necesarios para acceder al punto de conexión. Para obtener más información, vea «Solución de problemas de API de REST».
Elección de permisos para el acceso a GraphQL API
En el caso de las solicitudes de GraphQL, debes probar la aplicación para asegurarte de que tiene los permisos necesarios para las consultas y mutaciones de GraphQL que deseas realizar.
Si la aplicación realiza una consulta o mutación de GraphQL API con permisos insuficientes, la API devolverá una respuesta 401.
Elección de permisos para el acceso de Git
Si quieres que la aplicación use un token de acceso de instalación o usuario para autenticarse para el acceso a Git basado en HTTP, debes solicitar el permiso de repositorio "Contenido". Si la aplicación necesita específicamente acceder o editar archivos de acciones en el directorio .github/workflows, solicita el permiso de repositorio "Flujos de trabajo".
Después, puedes usar el token de acceso como contraseña HTTP. Reemplaza TOKEN por el token de acceso:
git clone https://x-access-token:TOKEN@github.com/owner/repo.git