招待API

グループやプロジェクトにユーザーを招待したり追加したり、保留中の招待を一覧表示するには、Invitations API を使用します。

有効なアクセスレベル

招待状を送信するには、メールを送信するプロジェクトまたはグループへのアクセス権が必要です。有効なアクセスレベルはGitlab::Access モジュールで定義されています。現在、以下のレベルが有効です：

  • アクセス不可 (0)
  • 最小アクセス (5) (GitLab 13.5 で導入)
  • ゲスト (10)
  • レポーター (20)
  • 開発者 (30)
  • メンテナー (40)
  • オーナー (50).GitLab 14.9 以降のプロジェクトで有効です。
note
GitLab 14.9以降では、プロジェクトの最大ロールはOwnerです。GitLab 14.8以前の既知のイシューのため、プロジェクトの最大ロールはメンテナーです。

グループやプロジェクトへのメンバーの追加

新しいメンバーを追加します。ユーザーIDを指定したり、メールでユーザーを招待することができます。

POST /groups/:id/invitations
POST /projects/:id/invitations
属性種類必須説明
id整数/文字列yes認証されたユーザーが所有するプロジェクトまたはグループのIDまたはURLエンコードされたパス
email文字列です。yes (user_id が提供されない場合)新メンバーのEメール、またはカンマで区切られた複数のEメール。
user_id整数/文字列yes (email が提供されない場合)新しいメンバーのID、またはカンマで区切られた複数のID。GitLab 14.10 で導入。
access_level整数。yes有効なアクセスレベル
expires_at文字列です。いいえYEAR-MONTH-DAY形式の日付文字列。
invite_source文字列です。いいえメンバ作成プロセスを開始する招待のソース。このイシューを参照してください。
tasks_to_be_done文字列の配列。いいえ招待者がメンバーに注目してほしいタスク。タスクは指定されたプロジェクトのイシューとして追加されます。指定できる値は次のとおりです：ci code とissuesが指定された場合、tasks_project_idが必要です。GitLab 14.6 で導入されました。
tasks_project_id整数。いいえタスク・イシューを作成するプロジェクトID。指定された場合、tasks_to_be_done が必要です。GitLab 14.6 で導入されました。
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --data "email=test@example.com&user_id=1&access_level=30" "https://gitlab.example.com/api/v4/groups/:id/invitations"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --data "email=test@example.com&user_id=1&access_level=30" "https://gitlab.example.com/api/v4/projects/:id/invitations"

レスポンスの例

すべてのメールが正常に送信された場合

{  "status":  "success"  }

送信エラーが発生した場合

{
  "status": "error",
  "message": {
               "test@example.com": "Invite email has already been taken",
               "test2@example.com": "User already exists in source",
               "test_username": "Access level is not included in the list"
             }
}

グループまたはプロジェクトで保留中のすべての招待をリストアップします。

認証ユーザーが表示可能な、招待されたグループまたはプロジェクトのメンバーのリストを取得します。直接のメンバーへの招待のみを返し、継承された先祖のグループへの招待は返しません。

この関数は、ページ分割パラメータpage とper_page を受け取り、メンバーのリストを制限します。

GET /groups/:id/invitations
GET /projects/:id/invitations
属性種類必須説明
id整数/文字列yes認証されたユーザーが所有するプロジェクトまたはグループのIDまたはURLエンコードされたパス
page整数。いいえ検索ページ
per_page整数。いいえ1ページに返信する会員招待の数
query文字列です。いいえ招待メールで招待メンバーを検索するためのクエリ文字列。クエリテキストはメールアドレスと正確に一致する必要があります。空の場合、すべての招待を返します。
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/invitations?query=member@example.org"
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/invitations?query=member@example.org"

応答例

 [
   {
     "id": 1,
     "invite_email": "member@example.org",
     "created_at": "2020-10-22T14:13:35Z",
     "access_level": 30,
     "expires_at": "2020-11-22T14:13:35Z",
     "user_name": "Raymond Smith",
     "created_by_name": "Administrator"
   },
]

グループまたはプロジェクトへの招待の更新

保留中の招待状のアクセスレベルまたはアクセス有効期限を更新します。

PUT /groups/:id/invitations/:email
PUT /projects/:id/invitations/:email
属性種類必須説明
id整数/文字列yes認証されたユーザーが所有するプロジェクトまたはグループのIDまたはURLエンコードされたパス。
email文字列です。yes招待状が以前に送信されたEメールアドレス。
access_level整数。いいえ有効なアクセス・レベル (デフォルト:30 、開発者ロール)。
expires_at文字列です。いいえISO 8601 形式 (YYYY-MM-DDTHH:MM:SSZ) の日付文字列。
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/55/invitations/email@example.org?access_level=40"
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/55/invitations/email@example.org?access_level=40"

応答例

{
  "expires_at": "2012-10-22T14:13:35Z",
  "access_level": 40,
}

グループやプロジェクトへの招待の削除

保留中の招待状をアドレス別に削除します。

DELETE /groups/:id/invitations/:email
DELETE /projects/:id/invitations/:email
属性種類必須説明
id整数/文字列yes認証されたユーザーが所有するプロジェクトまたはグループのIDまたはURLエンコードされたパス
email文字列です。yes以前に招待状が送信されたメールアドレス
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/55/invitations/email@example.org"
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/55/invitations/email@example.org"
  • 成功した場合は204 を返し、内容は返されません。
  • 招待の削除が許可されていない場合は403 forbidden を返します。
  • 作成者が許可しており、そのメールアドレスに招待状が見つからない場合は404 not found を返します。
  • リクエストが有効であったが招待を削除できなかった場合は409 を返します。