正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

タグAPI

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

このAPIを使用して、Gitタグを管理します。このAPIは、署名付きタグのX.509署名情報も返します。

プロジェクトリポジトリタグをリストする

プロジェクトから、更新日時で降順にソートされたリポジトリタグの一覧を取得します。

リポジトリが公開されている場合、認証（--header "PRIVATE-TOKEN: <your_access_token>"）は必要ありません。

GET /projects/:id/repository/tags

サポートされている属性:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
order_by文字列いいえname、updated、またはversionでタグを並べ替えて返します。versionは、セマンティックバージョン番号で並べ替えます。デフォルトはupdatedです。
page整数いいえページネーションの現在のページ番号。デフォルトは1です。
page_token文字列いいえページネーションを開始するタグの名前。キーセットページネーションに使用されます。
search文字列いいえ検索条件に一致するタグの一覧を返します。^termとterm$を使用して、termで始まるタグと終わるタグを検索できます。他の正規表現はサポートされていません。
sort文字列いいえascまたはdescの順にソートされたタグを返します。デフォルトはdescです。

成功した場合は、200 OKと以下のレスポンス属性が返されます:

属性型説明
commitオブジェクトタグに関連付けられたコミット情報。
commit.author_email文字列コミットの作成者のメールアドレス。
commit.author_name文字列コミットの作成者名。
commit.authored_date文字列コミットがISO 8601形式で作成された日付。
commit.committed_date文字列コミットがISO 8601形式でコミットされた日付。
commit.committer_email文字列コミッターのメールアドレス。
commit.committer_name文字列コミッターの名前。
commit.created_at文字列コミットがISO 8601形式で作成された日付。
commit.id文字列コミットの完全なSHA。
commit.message文字列コミットメッセージ。
commit.parent_ids配列親コミットSHAの配列。
commit.short_id文字列コミットの短いSHA。
commit.title文字列コミットのタイトル。
created_at文字列タグがISO 8601形式で作成された日付。
message文字列タグメッセージ。
name文字列タグの名前。
protectedブール値trueの場合、タグは保護されます。
releaseオブジェクトタグに関連付けられたリリース情報。
release.description文字列リリースに関する説明。
release.tag_name文字列リリースのタグ名。
target文字列タグが指すSHA。

リクエスト例:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "https://gitlab.example.com/api/v4/projects/5/repository/tags"

レスポンス例:

[
  {
    "commit": {
      "id": "2695effb5807a22ff3d138d593fd856244e155e7",
      "short_id": "2695effb",
      "title": "Initial commit",
      "created_at": "2017-07-26T11:08:53.000+02:00",
      "parent_ids": [
        "2a4b78934375d7f53875269ffd4f45fd83a84ebe"
      ],
      "message": "Initial commit",
      "author_name": "John Smith",
      "author_email": "john@example.com",
      "authored_date": "2012-05-28T04:42:42-07:00",
      "committer_name": "Jack Smith",
      "committer_email": "jack@example.com",
      "committed_date": "2012-05-28T04:42:42-07:00"
    },
    "release": {
      "tag_name": "1.0.0",
      "description": "Amazing release. Wow"
    },
    "name": "v1.0.0",
    "target": "2695effb5807a22ff3d138d593fd856244e155e7",
    "message": null,
    "protected": true,
    "created_at": "2017-07-26T11:08:53.000+02:00"
  }
]

単一リポジトリタグを取得する

名前で指定された特定のリポジトリタグを取得します。リポジトリが公開されている場合、このエンドポイントは認証なしでアクセスできます。

GET /projects/:id/repository/tags/:tag_name

サポートされている属性:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
tag_name文字列はいタグの名前。

成功した場合は、200 OKと以下のレスポンス属性が返されます:

属性型説明
commitオブジェクトタグに関連付けられたコミット情報。
commit.author_email文字列コミットの作成者のメールアドレス。
commit.author_name文字列コミットの作成者名。
commit.authored_date文字列コミットがISO 8601形式で作成された日付。
commit.committed_date文字列コミットがISO 8601形式でコミットされた日付。
commit.committer_email文字列コミッターのメールアドレス。
commit.committer_name文字列コミッターの名前。
commit.created_at文字列コミットがISO 8601形式で作成された日付。
commit.id文字列コミットの完全なSHA。
commit.message文字列コミットメッセージ。
commit.parent_ids配列親コミットSHAの配列。
commit.short_id文字列コミットの短いSHA。
commit.title文字列コミットのタイトル。
created_at文字列タグがISO 8601形式で作成された日付。
message文字列タグメッセージ。
name文字列タグの名前。
protectedブール値trueの場合、タグは保護されます。
releaseオブジェクトタグに関連付けられたリリース情報。
target文字列タグが指すSHA。

リクエスト例:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/tags/v1.0.0"

レスポンス例:

{
  "name": "v5.0.0",
  "message": null,
  "target": "60a8ff033665e1207714d6670fcd7b65304ec02f",
  "commit": {
    "id": "60a8ff033665e1207714d6670fcd7b65304ec02f",
    "short_id": "60a8ff03",
    "title": "Initial commit",
    "created_at": "2017-07-26T11:08:53.000+02:00",
    "parent_ids": [
      "f61c062ff8bcbdb00e0a1b3317a91aed6ceee06b"
    ],
    "message": "v5.0.0\n",
    "author_name": "Arthur Verschaeve",
    "author_email": "contact@arthurverschaeve.be",
    "authored_date": "2015-02-01T21:56:31.000+01:00",
    "committer_name": "Arthur Verschaeve",
    "committer_email": "contact@arthurverschaeve.be",
    "committed_date": "2015-02-01T21:56:31.000+01:00"
  },
  "release": null,
  "protected": false,
  "created_at": "2017-07-26T11:08:53.000+02:00"
}

新しいタグを作成する

指定された参照を指す、新しいタグをリポジトリに作成します。

POST /projects/:id/repository/tags

サポートされている属性:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
ref文字列はいコミットSHA、別のタグ名、またはブランチ名からタグを作成します。
tag_name文字列はいタグの名前。
message文字列いいえ注釈付きタグを作成します。

成功した場合は、201 Createdと以下のレスポンス属性が返されます:

属性型説明
commitオブジェクトタグに関連付けられたコミット情報。
commit.author_email文字列コミットの作成者のメールアドレス。
commit.author_name文字列コミットの作成者名。
commit.authored_date文字列コミットがISO 8601形式で作成された日付。
commit.committed_date文字列コミットがISO 8601形式でコミットされた日付。
commit.committer_email文字列コミッターのメールアドレス。
commit.committer_name文字列コミッターの名前。
commit.created_at文字列コミットがISO 8601形式で作成された日付。
commit.id文字列コミットの完全なSHA。
commit.message文字列コミットメッセージ。
commit.parent_ids配列親コミットSHAの配列。
commit.short_id文字列コミットの短いSHA。
commit.title文字列コミットのタイトル。
created_at文字列タグがISO 8601形式で作成された日付。
message文字列タグメッセージ。
name文字列タグの名前。
protectedブール値trueの場合、タグは保護されます。
releaseオブジェクトタグに関連付けられたリリース情報。
target文字列タグが指すSHA。

リクエスト例:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/tags?tag_name=test&ref=main"

レスポンス例:

{
  "commit": {
    "id": "2695effb5807a22ff3d138d593fd856244e155e7",
    "short_id": "2695effb",
    "title": "Initial commit",
    "created_at": "2017-07-26T11:08:53.000+02:00",
    "parent_ids": [
      "2a4b78934375d7f53875269ffd4f45fd83a84ebe"
    ],
    "message": "Initial commit",
    "author_name": "John Smith",
    "author_email": "john@example.com",
    "authored_date": "2012-05-28T04:42:42-07:00",
    "committer_name": "Jack Smith",
    "committer_email": "jack@example.com",
    "committed_date": "2012-05-28T04:42:42-07:00"
  },
  "release": null,
  "name": "v1.0.0",
  "target": "2695effb5807a22ff3d138d593fd856244e155e7",
  "message": null,
  "protected": false,
  "created_at": null
}

作成されたタグの種類によって、created_at、target、およびmessageの内容が決まります:

  • 注釈付きタグの場合:
    • created_atには、タグ作成時のタイムスタンプが含まれています。
    • messageには、注釈が含まれています。
    • targetには、タグオブジェクトのIDが含まれています。
  • 軽量タグの場合:
    • created_atはnullです。
    • messageはnullです。
    • targetには、コミットIDが含まれています。

エラーが発生した場合、ステータスコード405と説明的なエラーメッセージが返されます。

タグを削除する

指定された名前のリポジトリのタグを削除します。

DELETE /projects/:id/repository/tags/:tag_name

サポートされている属性:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
tag_name文字列はいタグの名前。

タグのX.509署名を取得する

タグが署名されている場合にタグからX.509署名を取得します。署名されていないタグは、404 Not Found応答を返します。

GET /projects/:id/repository/tags/:tag_name/signature

サポートされている属性:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
tag_name文字列はいタグの名前。

成功した場合は、200 OKと以下のレスポンス属性が返されます:

属性型説明
signature_type文字列署名のタイプ（X509）。
verification_status文字列署名の検証状態。
x509_certificateオブジェクトX.509証明書情報。
x509_certificate.certificate_status文字列証明書のステータス。
x509_certificate.email文字列証明書からのメールアドレス。
x509_certificate.id整数証明書のID。
x509_certificate.serial_number整数証明書のシリアル番号。
x509_certificate.subject文字列証明書のサブジェクト。
x509_certificate.subject_key_identifier文字列証明書のサブジェクトキー識別子。
x509_certificate.x509_issuerオブジェクト証明書の発行者情報。
x509_certificate.x509_issuer.crl_url文字列証明書失効リストのURL。
x509_certificate.x509_issuer.id整数発行者のID。
x509_certificate.x509_issuer.subject文字列発行者のサブジェクト。
x509_certificate.x509_issuer.subject_key_identifier文字列発行者のサブジェクトキー識別子。

リクエスト例:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/repository/tags/v1.1.1/signature"

タグがX.509署名されている場合の応答例:

{
  "signature_type": "X509",
  "verification_status": "unverified",
  "x509_certificate": {
    "id": 1,
    "subject": "CN=gitlab@example.org,OU=Example,O=World",
    "subject_key_identifier": "BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC",
    "email": "gitlab@example.org",
    "serial_number": 278969561018901340486471282831158785578,
    "certificate_status": "good",
    "x509_issuer": {
      "id": 1,
      "subject": "CN=PKI,OU=Example,O=World",
      "subject_key_identifier": "AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB",
      "crl_url": "http://example.com/pki.crl"
    }
  }
}

タグが署名されていない場合の応答例:

{
  "message": "404 GPG Signature Not Found"
}