Skip to content
代码片段 群组 项目
未验证 提交 450f7f33 编辑于 作者: Ben King's avatar Ben King 提交者： GitLab
浏览文件

Add pages domain verify API 

A new API endpoint for GitLab Pages has been added.
This allows for automated verification once a DNS
record has been configured.

Changelog: added
上级 d78a0bff
No related branches found
No related tags found
无相关合并请求
隐藏空白变更内容
行内 左右并排
doc/api/pages_domains.md
+ 188
− 11
浏览文件 @ 450f7f33
...@@ -26,16 +26,39 @@ Get a list of all Pages domains. ...@@ -26,16 +26,39 @@ Get a list of all Pages domains.
GET /pages/domains GET /pages/domains
``` ```
If successful, returns [`200`](rest/troubleshooting.md#status-codes) and the following
response attributes:
| Attribute | Type | Description |
| ------------------- | --------------- | ---------------------------------------- |
| `domain` | string | The custom domain name for the GitLab Pages site. |
| `url` | string | The full URL of the Pages site, including the protocol. |
| `project_id` | integer | The ID of the GitLab project associated with this Pages domain. |
| `verified` | boolean | Indicates whether the domain has been verified. |
| `verification_code` | string | A unique record used to verify domain ownership. |
| `enabled_until` | date | The date until which the domain is enabled. This updates periodically as the domain is reverified. |
| `auto_ssl_enabled` | boolean | Indicates if [automatic generation](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) of SSL certificates using Let's Encrypt is enabled for this domain. |
| `certificate_expiration` | object | Information about the SSL certificate expiration. |
| `certificate_expiration.expired` | boolean | Indicates whether the SSL certificate has expired. |
| `certificate_expiration.expiration` | date | The expiration date and time of the SSL certificate. |
Example request:
```shell ```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/pages/domains" curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/pages/domains"
``` ```
Example response:
```json ```json
[ [
{ {
"domain": "ssl.domain.example", "domain": "ssl.domain.example",
"url": "https://ssl.domain.example", "url": "https://ssl.domain.example",
"project_id": 1337, "project_id": 1337,
"verified": true,
"verification_code": "1234567890abcdef",
"enabled_until": "2020-04-12T14:32:00.000Z",
"auto_ssl_enabled": false, "auto_ssl_enabled": false,
"certificate": { "certificate": {
"expired": false, "expired": false,
...@@ -53,23 +76,53 @@ Get a list of project Pages domains. The user must have permissions to view Page ...@@ -53,23 +76,53 @@ Get a list of project Pages domains. The user must have permissions to view Page
GET /projects/:id/pages/domains GET /projects/:id/pages/domains
``` ```
Supported attributes:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- | | --------- | -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) |
If successful, returns [`200`](rest/troubleshooting.md#status-codes) and the following
response attributes:
| Attribute | Type | Description |
| ------------------- | --------------- | ---------------------------------------- |
| `domain` | string | The custom domain name for the GitLab Pages site. |
| `url` | string | The full URL of the Pages site, including the protocol. |
| `verified` | boolean | Indicates whether the domain has been verified. |
| `verification_code` | string | A unique record used to verify domain ownership. |
| `enabled_until` | date | The date until which the domain is enabled. This updates periodically as the domain is reverified. |
| `auto_ssl_enabled` | boolean | Indicates if [automatic generation](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) of SSL certificates using Let's Encrypt is enabled for this domain. |
| `certificate` | object | Information about the SSL certificate. |
| `certificate.subject` | string | The subject of the SSL certificate, typically containing information about the domain. |
| `certificate.expired` | date | Indicates whether the SSL certificate has expired (true) or is still valid (false). |
| `certificate.certificate` | string | The full SSL certificate in PEM format. |
| `certificate.certificate_text` | date | A human-readable text representation of the SSL certificate, including details such as issuer, validity period, subject, and other certificate information. |
Example request:
```shell ```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains" curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains"
``` ```
Example response:
```json ```json
[ [
{ {
"domain": "www.domain.example", "domain": "www.domain.example",
"url": "http://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", "domain": "ssl.domain.example",
"url": "https://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, "auto_ssl_enabled": false,
"certificate": { "certificate": {
"subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate", "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
...@@ -89,30 +142,45 @@ Get a single project Pages domain. The user must have permissions to view Pages ...@@ -89,30 +142,45 @@ Get a single project Pages domain. The user must have permissions to view Pages
GET /projects/:id/pages/domains/:domain GET /projects/:id/pages/domains/:domain
``` ```
Supported attributes:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- | | --------- | -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) |
| `domain` | string | yes | The custom domain indicated by the user | | `domain` | string | yes | The custom domain indicated by the user |
```shell If successful, returns [`200`](rest/troubleshooting.md#status-codes) and the following
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains/www.domain.example" response attributes:
```
| Attribute | Type | Description |
```json | ------------------- | --------------- | ---------------------------------------- |
{ | `domain` | string | The custom domain name for the GitLab Pages site. |
"domain": "www.domain.example", | `url` | string | The full URL of the Pages site, including the protocol. |
"url": "http://www.domain.example" | `verified` | boolean | Indicates whether the domain has been verified. |
} | `verification_code` | string | A unique record used to verify domain ownership. |
``` | `enabled_until` | date | The date until which the domain is enabled. This updates periodically as the domain is reverified. |
| `auto_ssl_enabled` | boolean | Indicates if [automatic generation](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) of SSL certificates using Let's Encrypt is enabled for this domain. |
| `certificate` | object | Information about the SSL certificate. |
| `certificate.subject` | string | The subject of the SSL certificate, typically containing information about the domain. |
| `certificate.expired` | date | Indicates whether the SSL certificate has expired (true) or is still valid (false). |
| `certificate.certificate` | string | The full SSL certificate in PEM format. |
| `certificate.certificate_text` | date | A human-readable text representation of the SSL certificate, including details such as issuer, validity period, subject, and other certificate information. |
Example request:
```shell ```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example" curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"
``` ```
Example response:
```json ```json
{ {
"domain": "ssl.domain.example", "domain": "ssl.domain.example",
"url": "https://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, "auto_ssl_enabled": false,
"certificate": { "certificate": {
"subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate", "subject": "/O=Example, Inc./OU=Example Origin CA/CN=Example Origin Certificate",
...@@ -131,6 +199,8 @@ Creates a new Pages domain. The user must have permissions to create new Pages d ...@@ -131,6 +199,8 @@ Creates a new Pages domain. The user must have permissions to create new Pages d
POST /projects/:id/pages/domains POST /projects/:id/pages/domains
``` ```
Supported attributes:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| -------------------| -------------- | -------- | ---------------------------------------- | | -------------------| -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) |
...@@ -139,6 +209,25 @@ POST /projects/:id/pages/domains ...@@ -139,6 +209,25 @@ POST /projects/:id/pages/domains
| `certificate` | file/string | no | The certificate in PEM format with intermediates following in most specific to least specific order.| | `certificate` | file/string | no | The certificate in PEM format with intermediates following in most specific to least specific order.|
| `key` | file/string | no | The certificate key in PEM format. | | `key` | file/string | no | The certificate key in PEM format. |
If successful, returns [`201`](rest/troubleshooting.md#status-codes) and the following
response attributes:
| Attribute | Type | Description |
| ------------------- | --------------- | ---------------------------------------- |
| `domain` | string | The custom domain name for the GitLab Pages site. |
| `url` | string | The full URL of the Pages site, including the protocol. |
| `verified` | boolean | Indicates whether the domain has been verified. |
| `verification_code` | string | A unique record used to verify domain ownership. |
| `enabled_until` | date | The date until which the domain is enabled. This updates periodically as the domain is reverified. |
| `auto_ssl_enabled` | boolean | Indicates if [automatic generation](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) of SSL certificates using Let's Encrypt is enabled for this domain. |
| `certificate` | object | Information about the SSL certificate. |
| `certificate.subject` | string | The subject of the SSL certificate, typically containing information about the domain. |
| `certificate.expired` | date | Indicates whether the SSL certificate has expired (true) or is still valid (false). |
| `certificate.certificate` | string | The full SSL certificate in PEM format. |
| `certificate.certificate_text` | date | A human-readable text representation of the SSL certificate, including details such as issuer, validity period, subject, and other certificate information. |
Example requests:
Create a new Pages domain with a certificate from a `.pem` file: Create a new Pages domain with a certificate from a `.pem` file:
```shell ```shell
...@@ -162,6 +251,8 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain ...@@ -162,6 +251,8 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain
--form "auto_ssl_enabled=true" "https://gitlab.example.com/api/v4/projects/5/pages/domains" --form "auto_ssl_enabled=true" "https://gitlab.example.com/api/v4/projects/5/pages/domains"
``` ```
Example response:
```json ```json
{ {
"domain": "ssl.domain.example", "domain": "ssl.domain.example",
...@@ -184,6 +275,8 @@ Updates an existing project Pages domain. The user must have permissions to chan ...@@ -184,6 +275,8 @@ Updates an existing project Pages domain. The user must have permissions to chan
PUT /projects/:id/pages/domains/:domain PUT /projects/:id/pages/domains/:domain
``` ```
Supported attributes:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| ------------------ | -------------- | -------- | ---------------------------------------- | | ------------------ | -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) |
...@@ -192,6 +285,23 @@ PUT /projects/:id/pages/domains/:domain ...@@ -192,6 +285,23 @@ PUT /projects/:id/pages/domains/:domain
| `certificate` | file/string | no | The certificate in PEM format with intermediates following in most specific to least specific order.| | `certificate` | file/string | no | The certificate in PEM format with intermediates following in most specific to least specific order.|
| `key` | file/string | no | The certificate key in PEM format. | | `key` | file/string | no | The certificate key in PEM format. |
If successful, returns [`200`](rest/troubleshooting.md#status-codes) and the following
response attributes:
| Attribute | Type | Description |
| ------------------- | --------------- | ---------------------------------------- |
| `domain` | string | The custom domain name for the GitLab Pages site. |
| `url` | string | The full URL of the Pages site, including the protocol. |
| `verified` | boolean | Indicates whether the domain has been verified. |
| `verification_code` | string | A unique record used to verify domain ownership. |
| `enabled_until` | date | The date until which the domain is enabled. This updates periodically as the domain is reverified. |
| `auto_ssl_enabled` | boolean | Indicates if [automatic generation](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) of SSL certificates using Let's Encrypt is enabled for this domain. |
| `certificate` | object | Information about the SSL certificate. |
| `certificate.subject` | string | The subject of the SSL certificate, typically containing information about the domain. |
| `certificate.expired` | date | Indicates whether the SSL certificate has expired (true) or is still valid (false). |
| `certificate.certificate` | string | The full SSL certificate in PEM format. |
| `certificate.certificate_text` | date | A human-readable text representation of the SSL certificate, including details such as issuer, validity period, subject, and other certificate information. |
### Adding certificate ### Adding certificate
Add a certificate for a Pages domain from a `.pem` file: Add a certificate for a Pages domain from a `.pem` file:
...@@ -208,6 +318,8 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certifi ...@@ -208,6 +318,8 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certifi
--form "key=$KEY_PEM" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example" --form "key=$KEY_PEM" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"
``` ```
Example response:
```json ```json
{ {
"domain": "ssl.domain.example", "domain": "ssl.domain.example",
...@@ -229,6 +341,8 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ ...@@ -229,6 +341,8 @@ 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" --form "auto_ssl_enabled=true" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"
``` ```
Example response:
```json ```json
{ {
"domain": "ssl.domain.example", "domain": "ssl.domain.example",
...@@ -246,6 +360,8 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certifi ...@@ -246,6 +360,8 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certifi
--form "key=" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example" --form "key=" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"
``` ```
Example response:
```json ```json
{ {
"domain": "ssl.domain.example", "domain": "ssl.domain.example",
...@@ -254,6 +370,61 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certifi ...@@ -254,6 +370,61 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certifi
} }
``` ```
## Verify Pages domain
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21261) in GitLab 17.7.
Verifies an existing project Pages domain.
The user must have permissions to update Pages domains.
```plaintext
PUT /projects/:id/pages/domains/:domain/verify
```
Supported attributes:
| Attribute | Type | Required | Description |
| ------------------ | -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | The ID or URL-encoded path of the project |
| `domain` | string | yes | The custom domain to verify |
If successful, returns [`200`](rest/troubleshooting.md#status-codes) and the following
response attributes:
| Attribute | Type | Description |
| ------------------- | --------------- | ---------------------------------------- |
| `domain` | string | The custom domain name for the GitLab Pages site. |
| `url` | string | The full URL of the Pages site, including the protocol. |
| `verified` | boolean | Indicates whether the domain has been verified. |
| `verification_code` | string | A unique record used to verify domain ownership. |
| `enabled_until` | date | The date until which the domain is enabled. This updates periodically as the domain is reverified. |
| `auto_ssl_enabled` | boolean | Indicates if [automatic generation](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) of SSL certificates using Let's Encrypt is enabled for this domain. |
| `certificate` | object | Information about the SSL certificate. |
| `certificate.subject` | string | The subject of the SSL certificate, typically containing information about the domain. |
| `certificate.expired` | date | Indicates whether the SSL certificate has expired (true) or is still valid (false). |
| `certificate.certificate` | string | The full SSL certificate in PEM format. |
| `certificate.certificate_text` | date | A human-readable text representation of the SSL certificate, including details such as issuer, validity period, subject, and other certificate information. |
Example request:
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example/verify"
```
Example response:
```json
{
"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"
}
```
## Delete Pages domain ## Delete Pages domain
Deletes an existing project Pages domain. Deletes an existing project Pages domain.
...@@ -262,11 +433,17 @@ Deletes an existing project Pages domain. ...@@ -262,11 +433,17 @@ Deletes an existing project Pages domain.
DELETE /projects/:id/pages/domains/:domain DELETE /projects/:id/pages/domains/:domain
``` ```
Supported attributes:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- | | --------- | -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) |
| `domain` | string | yes | The custom domain indicated by the user | | `domain` | string | yes | The custom domain indicated by the user |
If successful, a `204 No Content` HTTP response with an empty body is expected.
Example request:
```shell ```shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example" curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"
``` ```
lib/api/pages_domains.rb
+ 19
− 0
浏览文件 @ 450f7f33
...@@ -147,6 +147,25 @@ def normalize_params_file_to_string ...@@ -147,6 +147,25 @@ def normalize_params_file_to_string
end end
end end
desc 'Verify a pages domain' do
success Entities::PagesDomain
end
params do
requires :domain, type: String, desc: 'The domain to verify'
end
put ":id/pages/domains/:domain/verify", requirements: PAGES_DOMAINS_ENDPOINT_REQUIREMENTS do
authorize! :update_pages, user_project
pages_domain = find_pages_domain!
result = ::VerifyPagesDomainService.new(pages_domain).execute
if result[:status] == :success
present pages_domain, with: Entities::PagesDomain
else
render_api_error!(result[:message], result[:http_status])
end
end
desc 'Delete a pages domain' desc 'Delete a pages domain'
params do params do
requires :domain, type: String, desc: 'The domain' requires :domain, type: String, desc: 'The domain'
......
spec/requests/api/pages_domains_spec.rb
+ 72
− 0
浏览文件 @ 450f7f33
...@@ -552,6 +552,78 @@ ...@@ -552,6 +552,78 @@
end end
end end
describe 'PUT /projects/:project_id/pages/domains/:domain/verify' do
let(:verify_domain_path) { "/projects/#{project.id}/pages/domains/#{pages_domain.domain}/verify" }
context 'when user is not authorized' do
it 'returns 401' do
put api(verify_domain_path)
expect(response).to have_gitlab_http_status(:unauthorized)
end
end
context 'when user is authorized' do
before do
project.add_maintainer(user)
end
context 'when user does not have sufficient permissions' do
before do
project.add_reporter(user)
end
it 'returns 403' do
put api(verify_domain_path, user)
expect(response).to have_gitlab_http_status(:forbidden)
end
end
context 'when domain does not exist' do
it 'returns 404' do
put api("/projects/#{project.id}/pages/domains/non-existent-domain.com/verify", user)
expect(response).to have_gitlab_http_status(:not_found)
end
end
context 'when verification succeeds' do
before do
allow_next_instance_of(VerifyPagesDomainService) do |service|
allow(service).to receive(:execute).and_return({ status: :success })
end
end
it 'returns the verified domain' do
put api(verify_domain_path, user)
expect(response).to have_gitlab_http_status(:success)
expect(json_response['domain']).to eq(pages_domain.domain)
end
end
context 'when verification fails' do
before do
allow_next_instance_of(VerifyPagesDomainService) do |service|
allow(service).to receive(:execute).and_return({
status: :error,
message: 'Verification failed',
http_status: :unprocessable_entity
})
end
end
it 'returns error message' do
put api(verify_domain_path, user)
expect(response).to have_gitlab_http_status(:unprocessable_entity)
expect(json_response['message']).to eq('Verification failed')
end
end
end
end
describe 'DELETE /projects/:project_id/pages/domains/:domain' do describe 'DELETE /projects/:project_id/pages/domains/:domain' do
shared_examples_for 'delete pages domain' do shared_examples_for 'delete pages domain' do
it 'deletes a pages domain' do it 'deletes a pages domain' do
......
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或