Codeberg Pages 2: Setting Up Subdomain for git-pages Back-end

By Artyom Bologov

So Codeberg Pages have finally moved to git-pages back-end. Which is nice, don’t get me wrong! It’s fast, it’s lean, it’s featureful. But… Codeberg Pages docs related to deployment are pretty obscure. And the maintainers don’t feel like fixing this. Thus this post: to explain my journey in setting up scheme-index.aartaka.me as a custom domain subdomain.

I have to link to Codeberg Pages docs for fairness. In case you can understand them all and set up your subdomain based on them, then nice! But I wasn’t able to get through them and had to experiment and make many mistakes in the process. Here’s what I did.

Important detail: I use Namecheap as my domain registrar and DNS provider. So some things in this post are specific to Namecheap. The notation is @ for apex domain and scheme-index for the subdomain (just for the sake of example.)

Create a Repository #

I’m not going to explain Git here. Just make a new repo on Codeberg. Don’t add a pages branch yet—it’d better be done later!

Subdomain: CNAME Record #

First, I needed to add some records. I already had ALIAS record for the root of the website. I only had to add a CNAME pointing the domain to the right codeberg.page subdomain: 

ALIAS @ codeberg.page.
CNAME scheme-index scheme-index.aartaka.codeberg.page.
DNS records to set up the subdomain

I don’t use the CNAME for root domain (aartaka.me,) because I also use it for email. CNAME conflicts with that. Thus ALIAS. But CNAME is safe for subdomains!

More DNS Records #

You have to prove that you own the subdomain and that it’s deployed from the right repository. So _git-pages-repository record: 

TXT _git-pages-repository.scheme-index https://codeberg.org/aartaka/scheme-index.git
Record authenticating you as a domain owner

Another thing that docs recommend is setting up a CAA record. With scary values of letsencrypt.org;accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/292520050;validationmethods=tls-alpn-01,http-01 and letsencrypt.org;accounturi=https://acme-staging-v02.api.letsencrypt.org/acme/acct/272029763;validationmethods=tls-alpn-01,http-01. However, Namecheap does not allow anything but domain in the CAA record. So mine looked like: 

CAA @ 0 issue "letsencrypt.org"
The only CAA record Namecheap allows me to make

It’s enough it seems.

(Optional) .domains File—Just to Be Safe #

I honestly have no idea what I’m doing here. Codeberg Docs mention that .domains file is no longer necessary. But I added it just in case: 

scheme-index.aartaka.me
scheme-index.aartaka.codeberg.page
pages.scheme-index.aartaka.codeberg.page
My .domains file

I guess just add it if something goes wrong?

Add a Forgejo Hook #

Finally, we can try deploying to the subdomain. This is done through the Forgejo webhook. Codeberg docs explain it well enough. One important gotcha: you should set the webhook target URL to the subdomain URL and not apex domain URL! So http://scheme-index.aartaka.me and not http://aartaka.me. I’m emphasizing this because I set it to the apex domain URL and it overwrote my main website. Whaaaaat.

So the final webhook will look like:

Target URL
http://scheme-index.aartaka.me (Notice the http—the first push should happen to an HTTP URL for git-pages reasons. You can change it to HTTPS after the first push.)
Branch filter
pages
All the other fields
Leave as-is, they are fine

Push and Enjoy! #

Now you can create a pages branch in the repository and make the first push. If everything is set up correctly, you website should be live in a couple of minutes. Don’t hurry too much though—things take time. Have patience. I didn’t have patience and look where it got me.

Chat log showing my frustration 

<aartaka> Hi y'all. I'm trying to deploy one of my projects to a subdomain
          from Codeberg repository consulting Codeberg Pages docs, and I seem
          to be getting something wrong. In a minute, I'll list what I did:
                                                                        [11:52]
<aartaka> - Created a repository: https://codeberg.org/aartaka/scheme-index
                                                                        [11:53]
<aartaka> - Created a .domains file with scheme-index.aartaka.me in it (should
          be unnecessary as per the docs)
<aartaka> - Created an ALIAS record scheme-index codeberg.page.
<aartaka> - Made a Forgejo hook to ping
          https://aartaka.codeberg.page/scheme-index/  [11:54]
<aartaka> - Made another one to ping http://scheme-index.aartaka.me
<aartaka> - Then fixed it to ping http://aartaka.me
<aartaka> - Added _git-pages-repository.scheme-index TXT record with
          https://codeberg.org/aartaka/scheme-index.git in it [11:55]
<aartaka> And it still fails to resolve at DNS stage, and when I ignore that,
          it fails with SSL errors
<aartaka> I tried to set the CAA records, but Namecheap does not allow me to
          set anything but "letsencrypt.org" [11:56]
<aartaka> So yeah, that's basically it.
<aartaka> Anyone has ideas on what's wrong?
<aartaka> Oh no, and now it fucked up https://aartaka.me [12:10]
<aartaka> > Then fixed it to ping http://aartaka.me [12:17]
<aartaka> This probably was the mistake that re-deployed scheme-index at
          https://aartaka.me
<aartaka> But I triggeret the webhook in the main repository and now
          https://aartaka.me is back
<aartaka> Can't say the same about scheme-index.aartaka.me: still unable to
          set it up [12:18]
<aartaka> It works now. I'm going to send a patch to the docs. [12:23]
Yeah, I annoyed people on #git-pages

I hope that your experience will be better than mine! Codeberg Pages deserve love and use. Smooth sailing with no icebergs in sight ⛵

Leave feedback! (via email) #