Acerca de GitHub App los permisos
GitHub Apps no tiene permisos de forma predeterminada. Al registrar un GitHub App, puede seleccionar permisos para la aplicación. Los permisos que seleccione determinan a qué puede hacer la aplicación con GitHublas API y a qué webhooks puede suscribirse la aplicación. Debes seleccionar los permisos mínimos necesarios para la aplicación.
Aunque GitHub Apps no tienen permisos de forma predeterminada, tienen permisos implícitos para leer recursos públicos cuando actúan en nombre de un usuario. Cuando un usuario autoriza a la aplicación a actuar en su nombre, GitHub App puede usar el token de acceso de usuario resultante para realizar solicitudes a la API REST y graphQL 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, empresa 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 de usuario u organización, ve y concede los permisos de repositorio y organización que solicitó la aplicación. También verán una lista de permisos de cuenta que la aplicación puede solicitar a 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.
Para obtener más información sobre cómo especificar permisos durante GitHub App el registro, consulte Registro de una aplicación de GitHub.
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.
Acerca de los cambios en los permisos
Puede modificar los permisos de las aplicaciones que posee o administrar en cualquier momento.
- Cuando un propietario de la empresa modifica los permisos de una aplicación propiedad de una cuenta de empresa, las organizaciones de la empresa aceptan automáticamente los cambios.
- Cuando un administrador de aplicaciones empresariales modifica los permisos de una aplicación propiedad de una cuenta de empresa, las organizaciones de la empresa también aceptan automáticamente los cambios en la empresa donde el administrador de aplicaciones también es propietario de la organización.
- Al modificar los permisos de una aplicación propiedad de un usuario u organización, al hacerlo, se pedirá al propietario de cada cuenta en la que se instaló la aplicación para aprobar los nuevos permisos. Si el propietario de la cuenta no aprueba los nuevos permisos, su instalación seguirá usando los permisos antiguos.
Para más información sobre cómo modificar permisos, consulta Modificación de un registro de aplicación de GitHub.
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 desea suscribirse, consulte la documentación del webhook para ver qué permisos GitHub App necesita 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 GitHub App página de registro, los eventos de webhook disponibles cambiarán a medida que cambie los permisos de la aplicación. Si no seleccionó permisos suficientes para suscribirse GitHub App a un evento, el evento 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 REST para cada punto de conexión indica si el punto de conexión funciona con GitHub Apps y 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 GitHub App de conexión de la API REST a los que puede acceder con cada permiso, consulte Permisos necesarios para aplicaciones de GitHub.
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 más información, consulta 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