debian-mirror-gitlab/doc/api/pages_domains.md

256 lines
9.4 KiB
Markdown
Raw Normal View History

2020-06-23 00:09:42 +05:30
---
stage: Release
group: Release Management
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
2018-03-17 18:26:18 +05:30
# Pages domains API
2020-04-22 19:07:51 +05:30
Endpoints for connecting custom domain(s) and TLS certificates in [GitLab Pages](https://about.gitlab.com/stages-devops-lifecycle/pages/).
2018-03-17 18:26:18 +05:30
The GitLab Pages feature must be enabled to use these endpoints. Find out more about [administering](../administration/pages/index.md) and [using](../user/project/pages/index.md) the feature.
2020-11-24 15:15:51 +05:30
## List all Pages domains
2018-03-17 18:26:18 +05:30
2020-11-24 15:15:51 +05:30
Get a list of all Pages domains. The user must have admin permissions.
2018-03-17 18:26:18 +05:30
2020-05-24 23:13:21 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
GET /pages/domains
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/pages/domains"
2018-03-17 18:26:18 +05:30
```
```json
[
{
"domain": "ssl.domain.example",
"url": "https://ssl.domain.example",
"project_id": 1337,
2019-12-26 22:10:19 +05:30
"auto_ssl_enabled": false,
2018-03-17 18:26:18 +05:30
"certificate": {
"expired": false,
"expiration": "2020-04-12T14:32:00.000Z"
}
}
]
```
2020-11-24 15:15:51 +05:30
## List Pages domains
2018-03-17 18:26:18 +05:30
2020-11-24 15:15:51 +05:30
Get a list of project Pages domains. The user must have permissions to view Pages domains.
2018-03-17 18:26:18 +05:30
2020-05-24 23:13:21 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
GET /projects/:id/pages/domains
```
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains"
2018-03-17 18:26:18 +05:30
```
```json
[
{
"domain": "www.domain.example",
"url": "http://www.domain.example"
},
{
"domain": "ssl.domain.example",
"url": "https://ssl.domain.example",
2019-12-26 22:10:19 +05:30
"auto_ssl_enabled": false,
2018-03-17 18:26:18 +05:30
"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"
}
}
]
```
2020-11-24 15:15:51 +05:30
## Single Pages domain
2018-03-17 18:26:18 +05:30
2020-11-24 15:15:51 +05:30
Get a single project Pages domain. The user must have permissions to view Pages domains.
2018-03-17 18:26:18 +05:30
2020-05-24 23:13:21 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
GET /projects/:id/pages/domains/:domain
```
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
2019-12-26 22:10:19 +05:30
| `domain` | string | yes | The custom domain indicated by the user |
2018-03-17 18:26:18 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains/www.domain.example"
2018-03-17 18:26:18 +05:30
```
```json
{
"domain": "www.domain.example",
"url": "http://www.domain.example"
}
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"
2018-03-17 18:26:18 +05:30
```
```json
{
"domain": "ssl.domain.example",
"url": "https://ssl.domain.example",
2019-12-26 22:10:19 +05:30
"auto_ssl_enabled": false,
2018-03-17 18:26:18 +05:30
"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"
}
}
```
2020-11-24 15:15:51 +05:30
## Create new Pages domain
2018-03-17 18:26:18 +05:30
2020-11-24 15:15:51 +05:30
Creates a new Pages domain. The user must have permissions to create new Pages domains.
2018-03-17 18:26:18 +05:30
2020-05-24 23:13:21 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
POST /projects/:id/pages/domains
```
2019-12-26 22:10:19 +05:30
| Attribute | Type | Required | Description |
| -------------------| -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `domain` | string | yes | The custom domain indicated by the user |
| `auto_ssl_enabled` | boolean | no | Enables [automatic generation](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) of SSL certificates issued by Let's Encrypt for custom domains. |
| `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. |
2018-03-17 18:26:18 +05:30
2020-11-24 15:15:51 +05:30
Create a new Pages domain with a certificate from a `.pem` file:
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
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"
2018-03-17 18:26:18 +05:30
```
2020-11-24 15:15:51 +05:30
Create a new Pages domain by using a variable containing the certificate:
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
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"
2018-03-17 18:26:18 +05:30
```
2020-11-24 15:15:51 +05:30
Create a new Pages domain with an [automatic certificate](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md#enabling-lets-encrypt-integration-for-your-custom-domain):
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
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"
2019-12-26 22:10:19 +05:30
```
2018-03-17 18:26:18 +05:30
```json
{
"domain": "ssl.domain.example",
"url": "https://ssl.domain.example",
2019-12-26 22:10:19 +05:30
"auto_ssl_enabled": true,
2018-03-17 18:26:18 +05:30
"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"
}
}
```
2020-11-24 15:15:51 +05:30
## Update Pages domain
2018-03-17 18:26:18 +05:30
2020-11-24 15:15:51 +05:30
Updates an existing project Pages domain. The user must have permissions to change an existing Pages domains.
2018-03-17 18:26:18 +05:30
2020-05-24 23:13:21 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
PUT /projects/:id/pages/domains/:domain
```
2019-12-26 22:10:19 +05:30
| Attribute | Type | Required | Description |
| ------------------ | -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `domain` | string | yes | The custom domain indicated by the user |
| `auto_ssl_enabled` | boolean | no | Enables [automatic generation](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) of SSL certificates issued by Let's Encrypt for custom domains. |
| `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. |
### Adding certificate
2018-03-17 18:26:18 +05:30
2020-11-24 15:15:51 +05:30
Add a certificate for a Pages domain from a `.pem` file:
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
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"
2018-03-17 18:26:18 +05:30
```
2020-11-24 15:15:51 +05:30
Add a certificate for a Pages domain by using a variable containing the certificate:
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
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"
2018-03-17 18:26:18 +05:30
```
```json
{
"domain": "ssl.domain.example",
"url": "https://ssl.domain.example",
2019-12-26 22:10:19 +05:30
"auto_ssl_enabled": false,
2018-03-17 18:26:18 +05:30
"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"
}
}
```
2019-12-26 22:10:19 +05:30
### Enabling Let's Encrypt integration for Pages custom domains
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
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"
2019-12-26 22:10:19 +05:30
```
```json
{
"domain": "ssl.domain.example",
"url": "https://ssl.domain.example",
"auto_ssl_enabled": true
}
```
### Removing certificate
To remove the SSL certificate attached to the Pages domain, run:
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
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"
2019-12-26 22:10:19 +05:30
```
```json
{
"domain": "ssl.domain.example",
"url": "https://ssl.domain.example",
"auto_ssl_enabled": false
}
```
2020-11-24 15:15:51 +05:30
## Delete Pages domain
2018-03-17 18:26:18 +05:30
2020-11-24 15:15:51 +05:30
Deletes an existing project Pages domain.
2018-03-17 18:26:18 +05:30
2020-05-24 23:13:21 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
DELETE /projects/:id/pages/domains/:domain
```
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
2019-12-26 22:10:19 +05:30
| `domain` | string | yes | The custom domain indicated by the user |
2018-03-17 18:26:18 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example"
2018-03-17 18:26:18 +05:30
```