{{< details >}}

  • Tier: 基础版，专业版，旗舰版
  • Offering: JihuLab.com, 私有化部署

{{< /details >}}

用于连接自定义域名和 TLS 证书的极狐GitLab Pages端点。

必须启用极狐GitLab Pages 功能才能使用这些端点。了解更多关于管理和使用该功能的信息。

列出所有 Pages 域名

先决条件：

  • 您必须拥有实例的管理员访问权限。

获取所有 Pages 域名的列表。

GET /pages/domains

如果成功，将返回200及以下响应属性：

属性 类型 描述
domain string 极狐GitLab Pages 站点的自定义域名。
url string Pages 站点的完整 URL，包括协议。
project_id integer 与此 Pages 域名关联的极狐GitLab 项目 ID。
verified boolean 指示域名是否已验证。
verification_code string 用于验证域名所有权的唯一记录。
enabled_until date 域名启用的日期。随着域名的重新验证，这一日期会定期更新。
auto_ssl_enabled boolean 指示是否为此域名启用了使用 Let’s Encrypt 自动生成 的 SSL 证书。
certificate_expiration object SSL 证书到期信息。
certificate_expiration.expired boolean 指示 SSL 证书是否已到期。
certificate_expiration.expiration date SSL 证书的到期日期和时间。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/pages/domains"

示例响应：

[
  {
    "domain": "ssl.domain.example",
    "url": "https://ssl.domain.example",
    "project_id": 1337,
    "verified": true,
    "verification_code": "1234567890abcdef",
    "enabled_until": "2020-04-12T14:32:00.000Z",
    "auto_ssl_enabled": false,
    "certificate": {
      "expired": false,
      "expiration": "2020-04-12T14:32:00.000Z"
    }
  }
]

列出 Pages 域名

获取项目 Pages 域名的列表。用户必须具有查看 Pages 域名的权限。

GET /projects/:id/pages/domains

支持的属性：

属性 类型 必需 描述
id integer/string 是 项目 ID 或项目的 URL 编码路径

如果成功，将返回200及以下响应属性：

属性 类型 描述
domain string 极狐GitLab Pages 站点的自定义域名。
url string Pages 站点的完整 URL，包括协议。
verified boolean 指示域名是否已验证。
verification_code string 用于验证域名所有权的唯一记录。
enabled_until date 域名启用的日期。随着域名的重新验证，这一日期会定期更新。
auto_ssl_enabled boolean 指示是否为此域名启用了使用 Let’s Encrypt 自动生成 的 SSL 证书。
certificate object SSL 证书信息。
certificate.subject string SSL 证书的主题，通常包含有关域名的信息。
certificate.expired date 指示 SSL 证书是否已到期（true）或仍然有效（false）。
certificate.certificate string 完整的 PEM 格式的 SSL 证书。
certificate.certificate_text date SSL 证书的人类可读文本表示，包括发行者、有效期、主题和其他证书信息。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains"

示例响应：

[
  {
    "domain": "www.domain.example",
    "url": "http://www.domain.example",
    "verified": true,
    "verification_code": "1234567890abcdef",
    "enabled_until": "2020-04-12T14:32:00.000Z",
    "auto_ssl_enabled": false,
  },
  {
    "domain": "ssl.domain.example",
    "url": "https://ssl.domain.example",
    "verified": true,
    "verification_code": "1234567890abcdef",
    "enabled_until": "2020-04-12T14:32:00.000Z",
    "auto_ssl_enabled": false,
    "certificate": {
      "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
      "expired": false,
      "certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
      "certificate_text": "Certificate:\n … \n"
    }
  }
]

单个 Pages 域名

获取单个项目 Pages 域名。用户必须具有查看 Pages 域名的权限。

GET /projects/:id/pages/domains/:domain

支持的属性：

属性 类型 必需 描述
id integer/string 是 项目 ID 或项目的 URL 编码路径
domain string 是 用户指示的自定义域名

如果成功，将返回200及以下响应属性：

属性 类型 描述
domain string 极狐GitLab Pages 站点的自定义域名。
url string Pages 站点的完整 URL，包括协议。
verified boolean 指示域名是否已验证。
verification_code string 用于验证域名所有权的唯一记录。
enabled_until date 域名启用的日期。随着域名的重新验证，这一日期会定期更新。
auto_ssl_enabled boolean 指示是否为此域名启用了使用 Let’s Encrypt 自动生成 的 SSL 证书。
certificate object SSL 证书信息。
certificate.subject string SSL 证书的主题，通常包含有关域名的信息。
certificate.expired date 指示 SSL 证书是否已到期（true）或仍然有效（false）。
certificate.certificate string 完整的 PEM 格式的 SSL 证书。
certificate.certificate_text date SSL 证书的人类可读文本表示，包括发行者、有效期、主题和其他证书信息。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"

示例响应：

{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "verified": true,
  "verification_code": "1234567890abcdef",
  "enabled_until": "2020-04-12T14:32:00.000Z",
  "auto_ssl_enabled": false,
  "certificate": {
    "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
    "expired": false,
    "certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
    "certificate_text": "Certificate:\n … \n"
  }
}

创建新的 Pages 域名

创建新的 Pages 域名。用户必须具有创建新 Pages 域名的权限。

POST /projects/:id/pages/domains

支持的属性：

属性 类型 必需 描述
id integer/string 是 项目 ID 或项目的 URL 编码路径
domain string 是 用户指示的自定义域名
auto_ssl_enabled boolean 否 为自定义域名启用由 Let’s Encrypt 签发的 SSL 证书自动生成。
certificate file/string 否 PEM 格式的证书，后面跟着从最具体到最不具体顺序的中间证书。
key file/string 否 PEM 格式的证书密钥。

如果成功，将返回201及以下响应属性：

属性 类型 描述
domain string 极狐GitLab Pages 站点的自定义域名。
url string Pages 站点的完整 URL，包括协议。
verified boolean 指示域名是否已验证。
verification_code string 用于验证域名所有权的唯一记录。
enabled_until date 域名启用的日期。随着域名的重新验证，这一日期会定期更新。
auto_ssl_enabled boolean 指示是否为此域名启用了使用 Let’s Encrypt 自动生成 的 SSL 证书。
certificate object SSL 证书信息。
certificate.subject string SSL 证书的主题，通常包含有关域名的信息。
certificate.expired date 指示 SSL 证书是否已到期（true）或仍然有效（false）。
certificate.certificate string 完整的 PEM 格式的 SSL 证书。
certificate.certificate_text date SSL 证书的人类可读文本表示，包括发行者、有效期、主题和其他证书信息。

示例请求：

使用 .pem 文件中的证书创建新的 Pages 域名：

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "domain=ssl.domain.example" --form "certificate=@/path/to/cert.pem" \
     --form "key=@/path/to/key.pem" "https://gitlab.example.com/api/v4/projects/5/pages/domains"

使用包含证书的变量创建新的 Pages 域名：

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "domain=ssl.domain.example" --form "certificate=$CERT_PEM" \
     --form "key=$KEY_PEM" "https://gitlab.example.com/api/v4/projects/5/pages/domains"

使用自动证书创建新的 Pages 域名：

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain=ssl.domain.example" \
     --form "auto_ssl_enabled=true" "https://gitlab.example.com/api/v4/projects/5/pages/domains"

示例响应：

{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "auto_ssl_enabled": true,
  "certificate": {
    "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
    "expired": false,
    "certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
    "certificate_text": "Certificate:\n … \n"
  }
}

更新 Pages 域名

更新现有项目 Pages 域名。用户必须具有更改现有 Pages 域名的权限。

PUT /projects/:id/pages/domains/:domain

支持的属性：

属性 类型 必需 描述
id integer/string 是 项目 ID 或项目的 URL 编码路径
domain string 是 用户指示的自定义域名
auto_ssl_enabled boolean 否 为自定义域名启用由 Let’s Encrypt 签发的 SSL 证书自动生成。
certificate file/string 否 PEM 格式的证书，后面跟着从最具体到最不具体顺序的中间证书。
key file/string 否 PEM 格式的证书密钥。

如果成功，将返回200及以下响应属性：

属性 类型 描述
domain string 极狐GitLab Pages 站点的自定义域名。
url string Pages 站点的完整 URL，包括协议。
verified boolean 指示域名是否已验证。
verification_code string 用于验证域名所有权的唯一记录。
enabled_until date 域名启用的日期。随着域名的重新验证，这一日期会定期更新。
auto_ssl_enabled boolean 指示是否为此域名启用了使用 Let’s Encrypt 自动生成 的 SSL 证书。
certificate object SSL 证书信息。
certificate.subject string SSL 证书的主题，通常包含有关域名的信息。
certificate.expired date 指示 SSL 证书是否已到期（true）或仍然有效（false）。
certificate.certificate string 完整的 PEM 格式的 SSL 证书。
certificate.certificate_text date SSL 证书的人类可读文本表示，包括发行者、有效期、主题和其他证书信息。

添加证书

从 .pem 文件添加 Pages 域名的证书：

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=@/path/to/cert.pem" \
     --form "key=@/path/to/key.pem" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"

使用包含证书的变量添加 Pages 域名的证书：

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=$CERT_PEM" \
     --form "key=$KEY_PEM" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"

示例响应：

{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "auto_ssl_enabled": false,
  "certificate": {
    "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
    "expired": false,
    "certificate": "-----BEGIN CERTIFICATE-----\n … \n-----END CERTIFICATE-----",
    "certificate_text": "Certificate:\n … \n"
  }
}

启用 Let’s Encrypt 集成以支持 Pages 自定义域名 

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "auto_ssl_enabled=true" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"

示例响应：

{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "auto_ssl_enabled": true
}

移除证书

要移除附加到 Pages 域名的 SSL 证书，请运行：

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=" \
     --form "key=" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"

示例响应：

{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "auto_ssl_enabled": false
}

验证 Pages 域名

{{< history >}}

  • 引入于极狐GitLab 17.7。

{{< /history >}}

验证现有项目 Pages 域名。用户必须具有更新 Pages 域名的权限。

PUT /projects/:id/pages/domains/:domain/verify

支持的属性：

属性 类型 必需 描述
id integer/string 是 项目 ID 或 URL 编码路径
domain string 是 要验证的自定义域名

如果成功，将返回200及以下响应属性：

属性 类型 描述
domain string 极狐GitLab Pages 站点的自定义域名。
url string Pages 站点的完整 URL，包括协议。
verified boolean 指示域名是否已验证。
verification_code string 用于验证域名所有权的唯一记录。
enabled_until date 域名启用的日期。随着域名的重新验证，这一日期会定期更新。
auto_ssl_enabled boolean 指示是否为此域名启用了使用 Let’s Encrypt 自动生成 的 SSL 证书。
certificate object SSL 证书信息。
certificate.subject string SSL 证书的主题，通常包含有关域名的信息。
certificate.expired date 指示 SSL 证书是否已到期（true）或仍然有效（false）。
certificate.certificate string 完整的 PEM 格式的 SSL 证书。
certificate.certificate_text date SSL 证书的人类可读文本表示，包括发行者、有效期、主题和其他证书信息。

示例请求：

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example/verify"

示例响应：

{
  "domain": "ssl.domain.example",
  "url": "https://ssl.domain.example",
  "auto_ssl_enabled": false,
  "verified": true,
  "verification_code": "1234567890abcdef",
  "enabled_until": "2020-04-12T14:32:00.000Z"
}

删除 Pages 域名

删除现有项目 Pages 域名。

DELETE /projects/:id/pages/domains/:domain

支持的属性：

属性 类型 必需 描述
id integer/string 是 项目 ID 或项目的 URL 编码路径
domain string 是 用户指示的自定义域名

如果成功，则应返回一个 204 No Content HTTP 响应，且正文为空。

示例请求：

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"