diff options
Diffstat (limited to 'doc/api/pages_domains.md')
-rw-r--r-- | doc/api/pages_domains.md | 71 |
1 files changed, 57 insertions, 14 deletions
diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index 9678203eb40..9d482781cde 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -22,6 +22,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap "domain": "ssl.domain.example", "url": "https://ssl.domain.example", "project_id": 1337, + "auto_ssl_enabled": false, "certificate": { "expired": false, "expiration": "2020-04-12T14:32:00.000Z" @@ -55,6 +56,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap { "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, @@ -76,7 +78,7 @@ 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 | -| `domain` | string | yes | The domain | +| `domain` | string | yes | The custom domain indicated by the user | ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/pages/domains/www.domain.example @@ -97,6 +99,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap { "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, @@ -114,12 +117,13 @@ Creates a new pages domain. The user must have permissions to create new pages d POST /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 | -| `domain` | string | yes | The domain | -| `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. | +| 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. | ```bash 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 @@ -129,10 +133,15 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain 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 ``` +```bash +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 +``` + ```json { "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, @@ -150,12 +159,15 @@ Updates an existing project pages domain. The user must have permissions to chan PUT /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 | -| `domain` | string | yes | The domain | -| `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. | +| 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 ```bash 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 @@ -169,6 +181,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certifi { "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, @@ -178,6 +191,36 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certifi } ``` +### Enabling Let's Encrypt integration for Pages custom domains + +```bash +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 +``` + +```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: + +```bash +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 +``` + +```json +{ + "domain": "ssl.domain.example", + "url": "https://ssl.domain.example", + "auto_ssl_enabled": false +} +``` + ## Delete pages domain Deletes an existing project pages domain. @@ -189,7 +232,7 @@ 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 | -| `domain` | string | yes | The domain | +| `domain` | string | yes | The custom domain indicated by the user | ```bash curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example |