Pages domains API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed

Endpoints for connecting custom domains and TLS certificates in GitLab Pages.

The GitLab Pages feature must be enabled to use these endpoints. Find out more about administering and using the feature.

List all Pages domains

Prerequisites:

  • You must have administrator access to the instance.

Get a list of all Pages domains.

GET /pages/domains

If successful, returns 200 and the following response attributes:

AttributeTypeDescription
domainstringThe custom domain name for the GitLab Pages site.
urlstringThe full URL of the Pages site, including the protocol.
project_idintegerThe ID of the GitLab project associated with this Pages domain.
verifiedbooleanIndicates whether the domain has been verified.
verification_codestringA unique record used to verify domain ownership.
enabled_untildateThe date until which the domain is enabled. This updates periodically as the domain is reverified.
auto_ssl_enabledbooleanIndicates if automatic generation of SSL certificates using Let’s Encrypt is enabled for this domain.
certificate_expirationobjectInformation about the SSL certificate expiration.
certificate_expiration.expiredbooleanIndicates whether the SSL certificate has expired.
certificate_expiration.expirationdateThe expiration date and time of the SSL certificate.

Example request:

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

Example response:

[
  {
    "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"
    }
  }
]

List Pages domains

Get a list of project Pages domains. The user must have permissions to view Pages domains.

GET /projects/:id/pages/domains

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project

If successful, returns 200 and the following response attributes:

AttributeTypeDescription
domainstringThe custom domain name for the GitLab Pages site.
urlstringThe full URL of the Pages site, including the protocol.
verifiedbooleanIndicates whether the domain has been verified.
verification_codestringA unique record used to verify domain ownership.
enabled_untildateThe date until which the domain is enabled. This updates periodically as the domain is reverified.
auto_ssl_enabledbooleanIndicates if automatic generation of SSL certificates using Let’s Encrypt is enabled for this domain.
certificateobjectInformation about the SSL certificate.
certificate.subjectstringThe subject of the SSL certificate, typically containing information about the domain.
certificate.expireddateIndicates whether the SSL certificate has expired (true) or is still valid (false).
certificate.certificatestringThe full SSL certificate in PEM format.
certificate.certificate_textdateA human-readable text representation of the SSL certificate, including details such as issuer, validity period, subject, and other certificate information.

Example request:

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

Example response:

[
  {
    "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"
    }
  }
]

Single Pages domain

Get a single project Pages domain. The user must have permissions to view Pages domains.

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

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project
domainstringyesThe custom domain indicated by the user

If successful, returns 200 and the following response attributes:

AttributeTypeDescription
domainstringThe custom domain name for the GitLab Pages site.
urlstringThe full URL of the Pages site, including the protocol.
verifiedbooleanIndicates whether the domain has been verified.
verification_codestringA unique record used to verify domain ownership.
enabled_untildateThe date until which the domain is enabled. This updates periodically as the domain is reverified.
auto_ssl_enabledbooleanIndicates if automatic generation of SSL certificates using Let’s Encrypt is enabled for this domain.
certificateobjectInformation about the SSL certificate.
certificate.subjectstringThe subject of the SSL certificate, typically containing information about the domain.
certificate.expireddateIndicates whether the SSL certificate has expired (true) or is still valid (false).
certificate.certificatestringThe full SSL certificate in PEM format.
certificate.certificate_textdateA human-readable text representation of the SSL certificate, including details such as issuer, validity period, subject, and other certificate information.

Example request:

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

Example response:

{
  "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"
  }
}

Create new Pages domain

Creates a new Pages domain. The user must have permissions to create new Pages domains.

POST /projects/:id/pages/domains

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project
domainstringyesThe custom domain indicated by the user
auto_ssl_enabledbooleannoEnables automatic generation of SSL certificates issued by Let’s Encrypt for custom domains.
certificatefile/stringnoThe certificate in PEM format with intermediates following in most specific to least specific order.
keyfile/stringnoThe certificate key in PEM format.

If successful, returns 201 and the following response attributes:

AttributeTypeDescription
domainstringThe custom domain name for the GitLab Pages site.
urlstringThe full URL of the Pages site, including the protocol.
verifiedbooleanIndicates whether the domain has been verified.
verification_codestringA unique record used to verify domain ownership.
enabled_untildateThe date until which the domain is enabled. This updates periodically as the domain is reverified.
auto_ssl_enabledbooleanIndicates if automatic generation of SSL certificates using Let’s Encrypt is enabled for this domain.
certificateobjectInformation about the SSL certificate.
certificate.subjectstringThe subject of the SSL certificate, typically containing information about the domain.
certificate.expireddateIndicates whether the SSL certificate has expired (true) or is still valid (false).
certificate.certificatestringThe full SSL certificate in PEM format.
certificate.certificate_textdateA 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:

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"

Create a new Pages domain by using a variable containing the certificate:

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"

Create a new Pages domain with an automatic certificate:

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"

Example response:

{
  "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"
  }
}

Update Pages domain

Updates an existing project Pages domain. The user must have permissions to change an existing Pages domains.

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

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project
domainstringyesThe custom domain indicated by the user
auto_ssl_enabledbooleannoEnables automatic generation of SSL certificates issued by Let’s Encrypt for custom domains.
certificatefile/stringnoThe certificate in PEM format with intermediates following in most specific to least specific order.
keyfile/stringnoThe certificate key in PEM format.

If successful, returns 200 and the following response attributes:

AttributeTypeDescription
domainstringThe custom domain name for the GitLab Pages site.
urlstringThe full URL of the Pages site, including the protocol.
verifiedbooleanIndicates whether the domain has been verified.
verification_codestringA unique record used to verify domain ownership.
enabled_untildateThe date until which the domain is enabled. This updates periodically as the domain is reverified.
auto_ssl_enabledbooleanIndicates if automatic generation of SSL certificates using Let’s Encrypt is enabled for this domain.
certificateobjectInformation about the SSL certificate.
certificate.subjectstringThe subject of the SSL certificate, typically containing information about the domain.
certificate.expireddateIndicates whether the SSL certificate has expired (true) or is still valid (false).
certificate.certificatestringThe full SSL certificate in PEM format.
certificate.certificate_textdateA human-readable text representation of the SSL certificate, including details such as issuer, validity period, subject, and other certificate information.

Adding certificate

Add a certificate for a Pages domain from a .pem file:

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"

Add a certificate for a Pages domain by using a variable containing the certificate:

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"

Example response:

{
  "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"
  }
}

Enabling Let’s Encrypt integration for Pages custom domains

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"

Example response:

{
  "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:

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"

Example response:

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

Verify Pages domain

History

Verifies an existing project Pages domain. The user must have permissions to update Pages domains.

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

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project
domainstringyesThe custom domain to verify

If successful, returns 200 and the following response attributes:

AttributeTypeDescription
domainstringThe custom domain name for the GitLab Pages site.
urlstringThe full URL of the Pages site, including the protocol.
verifiedbooleanIndicates whether the domain has been verified.
verification_codestringA unique record used to verify domain ownership.
enabled_untildateThe date until which the domain is enabled. This updates periodically as the domain is reverified.
auto_ssl_enabledbooleanIndicates if automatic generation of SSL certificates using Let’s Encrypt is enabled for this domain.
certificateobjectInformation about the SSL certificate.
certificate.subjectstringThe subject of the SSL certificate, typically containing information about the domain.
certificate.expireddateIndicates whether the SSL certificate has expired (true) or is still valid (false).
certificate.certificatestringThe full SSL certificate in PEM format.
certificate.certificate_textdateA human-readable text representation of the SSL certificate, including details such as issuer, validity period, subject, and other certificate information.

Example request:

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:

{
  "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

Deletes an existing project Pages domain.

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

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project
domainstringyesThe custom domain indicated by the user

If successful, a 204 No Content HTTP response with an empty body is expected.

Example request:

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