Custom domains

A repository can be served at the root of a domain that you control, so your builds resolve from https://maven.example.com/ instead of the Artifex URL.

You need the repository's Admin role, and the repository owner needs a plan that includes custom domains. See Plans.

Connect a domain

To connect a domain, follow these steps:

1. Open the repository and go to Domains.

2. Click New domain.

3. In the Hostname field, enter the hostname, such as maven.example.com.

   New domain

   Learn more

   Hostname *

   Pre-validate, because another host serves it now

4. Click Add domain.

5. At your DNS provider, add a CNAME record for that hostname pointing at the target that the page shows.

6. If the page shows a verification record, add that TXT record as well.

   DNS records for maven.example.com

   Create the following CNAME and TXT records.

   Type	Name	Value	Detected
   CNAME	maven.example.com	artifex.soh.gg	Detected
   TXT	_cf-custom-hostname.maven.example.com	5d1e0c3a-7b42-4f9e-9c11-2a8b6e4d0f13	Missing

7. Click Check status until the status is Active.

A hostname connects to one repository. Domains under soh.gg, and the Artifex URL itself, can't be used.

Move a domain from another host

If the domain already serves a repository on another host, pre-validate it. Artifex then validates the domain and issues its certificate with TXT records while the other host still serves the domain, and the domain moves to Artifex when you change its CNAME record. Copy the repository's contents first, so that builds find every file after the move.

To move a domain, follow these steps:

1. Open the repository and go to Domains.

2. Click New domain.

3. In the Hostname field, enter the hostname.

4. Select Pre-validate, because another host serves it now, and then click Add domain.

5. At your DNS provider, add the two TXT records that the page shows. Leave the CNAME record as it is.

   DNS records for maven.example.com

   Create the following TXT records. Change the CNAME record after the domain is active.

   Type	Name	Value	Detected
   TXT	_cf-custom-hostname.maven.example.com	5d1e0c3a-7b42-4f9e-9c11-2a8b6e4d0f13	Detected
   TXT	_acme-challenge.maven.example.com	Xq3n8W1bZ0yUe7fT4kLmR2sVd9pHc6jA5oGiNwE	Detected
   CNAME	maven.example.com	artifex.soh.gg	Missing

6. Click Check status until the status is Active. The certificate TXT record can take a few minutes to appear on the page.

7. Change the domain's CNAME record to the target that the page shows.

Builds that use the domain resolve from Artifex as soon as their DNS lookups see the new CNAME record. Leave the TXT records in place.

Let Artifex add the records

If the domain is on Cloudflare, click Set the records up for me in the domain's row and approve the request in Cloudflare. Artifex adds the records to the domain's zone. Check the status a moment later. For a pre-validated domain, Artifex adds only the TXT records until the domain is active. After that, the same button changes the CNAME record.

The records

Record	Name	Value
CNAME	The hostname that you added	The target shown on the Domains page
TXT	Shown on the page when verification is required	Shown next to the name
TXT	Shown on the page for a pre-validated domain	Shown next to the name

The Detected column shows whether each record was found, and a warning names any record that's missing.

Most DNS providers don't allow a CNAME record at the zone apex, so use a subdomain such as maven.example.com. Some providers offer CNAME flattening at the apex, which also works.

Status

Status	What it means	What to do
Pending DNS	The records aren't visible yet	Check the records and wait for them to propagate
Pending certificate	The records are visible and the certificate is being issued	Wait, then check the status again
Active	The domain serves the repository	Point your builds at it
Failed	Verification or certificate issuance didn't succeed	Read the message on the page, correct the records, and check again

Use the domain

After the status is Active, the repository is served at the root of the domain:

<repository>
  <id>artifex</id>
  <url>https://maven.example.com/</url>
</repository>

The Artifex URL continues to work, so you can move builds over one at a time. Changing the repository name doesn't affect the domain.

Choose the primary domain

While the repository's primary domain is Active, the repository's pages use it as the repository URL: the Maven address, the build snippets in Use this repository, and the download links. Otherwise, the pages use the Artifex URL.

The first domain that you add to a repository becomes its primary domain, and the Domains page marks it Primary. To make another domain primary, follow these steps:

1. Open the repository and go to Domains.
2. In the domain's row, click Make primary.

To use the Artifex URL instead, click Clear primary in the primary domain's row.

The repository's pages on the domain

The domain also serves the repository's pages. Opening https://maven.example.com/ shows the repository, and its pages are under /-/, such as https://maven.example.com/-/browse. Links to any other page, such as your tokens, open on the Artifex URL.

Disconnect a domain

To disconnect a domain, follow these steps:

1. Open the repository and go to Domains.
2. In the domain's row, click Remove.

The domain stops serving the repository. Remove the CNAME record afterwards. Builds that still use the domain fail until you point them at another repository URL.

Deleting a repository disconnects its domains.