Origin Grants API
Origin は Early Beta 段階であり、変更される可能性があります。
権限付与 は、1 つの プリンシパル を 1 つの リポジトリ または 名前空間 に、1 つの permission で紐付けるものです。権限付与 API では、resource に直接設定されている 権限付与 の一覧取得、プリンシパル が保持する 権限付与 の アップサート、およびその削除が行えます。これにより、access の変更をスクリプト化し、コードとして審査できます。書き込み操作は Codebase permissions UI の背後にある access チェックを再利用し、同じ repository.access_changed および namespace.access_changed の audit イベントを記録します。
6 つのエンドポイントは、Origin API リファレンスの Grants グループにあります: List Repository Grants、Upsert Repository Grant、Delete Repository Grant、List Namespace Grants、Upsert Namespace Grant、Delete Namespace Grant。これらのエンドポイントは、Origin API の base URL、認証、pagination、error モデルを共通で使用します。このページでは、その背後にある概念を説明します。
プリンシパル
各 権限付与 が指定する プリンシパル は必ず 1 つだけです。
| Principal | Field | 識別対象 |
|---|---|---|
user | user.id | organization API が使用する encoded な user_… id で識別される Cherri Code user。 |
group | group.id | public な grp_… id で識別される Cherri Code group。owner の team が所有する group か、その team の organization にある group のいずれかで、Organization API の group routes が publicId として返すものです。これらの routes が受け取る g_… の id は別の識別子です。 |
teamGroup | teamGroup.kind | owner となる team の built-in グループのいずれか: members (すべての team member) または admins (team admins) 。 |
team group への 権限付与 は、その built-in グループのすべての member が当該 resource に対して持つ権限の下限となります。名前空間 では team の 名前空間 floor として機能し、リポジトリ では team のリポジトリごとの override となり、削除すると リポジトリ は 名前空間 floor に戻ります。
user は owner の organization に属している必要があります。group は owner の team が所有するものか、その team の organization にある有効な group でなければなりません。team 自身の group は、その team が organization に linked されていない場合でも 権限付与 の対象にできます。write endpoints は、存在しない user または group に対しても organization 外のものとまったく同じように応答するため、レスポンス から プリンシパル の存在を確認することはできません。List のレスポンスでは、有効な user、group、または owner となる team に解決できなくなった プリンシパル は省略されます。
権限
リポジトリ grant と namespace grant では、権限の階層が異なります。いずれも Codebase permissions UI が提供するプリセットに対応しています。
| Resource | permission の値 |
|---|---|
| リポジトリ | read、write、admin |
| Namespace | PERMISSION_READ、PERMISSION_CONTRIBUTOR、PERMISSION_WRITE、PERMISSION_ADMIN |
PERMISSION_READ、PERMISSION_CONTRIBUTOR、PERMISSION_WRITE は、その namespace の internal リポジトリ に対して該当レベルの権限を付与します。PERMISSION_ADMIN は namespace 自体を管理する権限です。
List のレスポンスでは、custom policy を持つ grant について custom (リポジトリ) または PERMISSION_CUSTOM (namespace) が返されます。upsert の エンドポイント はこれらの値を InvalidArgument (HTTP 400) で拒否します。custom policy は grants API の対象外です。
Scopes
権限付与 API には 4 つの scope があり、いずれも Scopes に記載されています。リポジトリの 権限付与 用の repository:settings:read と repository:settings:write、名前空間 の 権限付与 用の namespace:settings:read と namespace:settings:write です。
アプリのインストールは 4 つすべてを保持できるため、ロボットは installation access token を使って 権限付与 API を呼び出します。ユーザーアクセストークンも使用できます。:write scope を要求すると、対応する :read scope も併せて付与されます。list エンドポイント は 1 ポイント、write は 5 ポイントを Rate limits の budget から消費します。
アップサート と削除
アップサート は POST で、プリンシパル が resource に対して保持する 権限付与 を作成または置き換えます。各 プリンシパル が resource ごとに保持する 権限付与 は 1 つのみのため、同じ request を繰り返しても 権限付与 はそのまま維持され、異なる permission を指定すると以前の 権限付与 が置き換えられます。削除は request body で プリンシパル を指定し、204 No Content を返します。
名前空間 には常に最低 1 人の admin が保持されます。owner に admin が 1 人もいない状態になる アップサート または削除は、FailedPrecondition (HTTP 400) を返します。