API de grants de Origin
Origin está en beta inicial y puede cambiar.
Un grant vincula un principal con un repositorio o espacio de nombres mediante un permiso. La API de grants lista los grants asignados directamente a un recurso, crea o actualiza el grant que tiene un principal y lo elimina, de modo que los cambios de acceso se pueden automatizar con scripts y revisar como código. Las operaciones de escritura reutilizan las comprobaciones de acceso que hay detrás de la UI de permisos de la base de código y registran los mismos eventos de auditoría repository.access_changed y namespace.access_changed.
Los seis endpoints están en el grupo Grants de la referencia de la API de Origin: List Repository Grants, Upsert Repository Grant, Delete Repository Grant, List Namespace Grants, Upsert Namespace Grant y Delete Namespace Grant. Comparten la URL base, la autenticación, la paginación y el modelo de errores de la API de Origin. Esta página explica los conceptos que hay detrás de ellos.
Principals
Cada grant nombra exactamente un principal.
| Principal | Field | Identifica |
|---|---|---|
user | user.id | Un usuario de Cherri Code, mediante el id user_… encoded que usa la API de organización. |
group | group.id | Un grupo de Cherri Code, mediante su id público grp_…: ya sea un grupo que posee el equipo del owner o un grupo de la organización de ese equipo, devuelto como publicId por las routes de grupo de la API de organización. El id g_… que reciben esas routes es un identificador distinto. |
teamGroup | teamGroup.kind | Uno de los grupos integrados del equipo propietario: members (todos los miembros del equipo) o admins (administradores de equipo). |
Un grant de team-group es el nivel mínimo que tiene cada miembro de ese grupo integrado sobre el recurso. En un espacio de nombres corresponde al namespace floor del equipo. En un repositorio corresponde al override por repositorio del equipo, y al eliminarlo el repositorio vuelve al namespace floor.
Los usuarios deben pertenecer a la organización del owner. Un grupo debe ser uno que posea el equipo del owner o un grupo activo de la organización de ese equipo; los grupos propios de un equipo se pueden conceder incluso cuando el equipo no está linked a una organización. Los endpoints de write responden a un usuario o grupo inexistente exactamente igual que a uno ajeno a la organización, por lo que una respuesta nunca confirma que un principal exista. Las respuestas de listado omiten los principals que ya no resuelven a un usuario activo, a un grupo o al equipo propietario.
Permisos
Los grants de repositorio y los grants de espacio de nombres usan escalas de permisos distintas. Ambas se corresponden con los preajustes que ofrece la UI de permisos de la base de código.
| Recurso | Valores de permission |
|---|---|
| Repositorio | read, write, admin |
| Espacio de nombres | PERMISSION_READ, PERMISSION_CONTRIBUTOR, PERMISSION_WRITE, PERMISSION_ADMIN |
PERMISSION_READ, PERMISSION_CONTRIBUTOR y PERMISSION_WRITE otorgan ese nivel sobre los repositorios internos del espacio de nombres. PERMISSION_ADMIN administra el espacio de nombres en sí.
Las respuestas de listado devuelven custom (repositorio) o PERMISSION_CUSTOM (espacio de nombres) cuando un grant tiene una custom policy. Los endpoints de creación o actualización rechazan esos valores con InvalidArgument (HTTP 400): las custom policies quedan fuera de la API de grants.
Scopes
Cuatro scopes cubren la API de grants, todos ellos listados en Scopes: repository:settings:read y repository:settings:write para los grants de repositorio, y namespace:settings:read y namespace:settings:write para los grants de espacio de nombres.
Las instalaciones de apps pueden tener los cuatro, por lo que un robot puede llamar a la API de grants con un token de acceso de instalación. Los tokens de acceso de usuario también sirven. Al solicitar un scope :write se otorga además el scope :read correspondiente. Los endpoints de listado cuestan 1 punto y las escrituras, 5 puntos del presupuesto descrito en Límites de uso.
Creaciones o actualizaciones y eliminaciones
Crear o actualizar es un POST que crea o reemplaza el grant que un principal tiene sobre el recurso. Cada principal tiene un único grant por recurso, por lo que repetir una solicitud mantiene el mismo grant y un permission distinto reemplaza el anterior. La eliminación indica el principal en el request body y devuelve 204 No Content.
Un espacio de nombres siempre conserva al menos un admin. Una creación o actualización, o una eliminación, que dejaría al owner sin ninguno devuelve FailedPrecondition (HTTP 400).