Publish a site with Pages

Pages publishes a branch of your repository as a static website. Pages is available when the site administrators of the instance have enabled it, as described in Pages for administrators. The examples on this page use pages.example.com as the instance’s Pages domain. The repository settings show the Pages domain of your instance.

Publish a site

You need admin access to the repository.

Open the repository’s Settings > Pages.
Select Enabled.
Choose the Branch with the site’s files. The default is pages.
Select Save settings.

If the branch does not exist yet, Arbinel creates it with a placeholder index.html that says Your site is live. The new branch has no history and shares no files with your other branches. Replace the placeholder with your own files.

Arbinel publishes the branch again on every push to it. The Site status section shows whether the latest deployment succeeded.

Enabling Pages also sets the repository’s website field to the site’s address.

Site content

Arbinel publishes the branch exactly as it is. It must contain the built site, which means the HTML, CSS and other files that your visitors receive, not the source files that generate them.

To generate the site with a tool such as Hugo, Astro or MkDocs, build it in a Forgejo Actions workflow and push the output to the Pages branch. Keep the source on another branch, so you never commit generated files to the branch you work in. Actions is off by default in a repository, so enable it in the repository settings first.

To publish only one directory of the branch, add a statichost.yml file at the root of the branch:

public: dist

The directory must exist in the branch. If it does not, or the file cannot be read, the whole branch is published.

Site address

The address depends on the backend that your instance uses. The Managed address field in the Pages settings always shows the correct address.

On instances with self-hosted git-pages nodes, all sites of one owner share one hostname:

Repository	Address
`alice/blog`	`https://alice.pages.example.com/blog/`
`alice/pages`	`https://alice.pages.example.com/`

A repository named pages is served at the root of the owner’s hostname. Accounts and organizations whose name contains a dot cannot publish a site on these instances.

On instances that use StaticHost, each site has its own hostname, https://<repo>.<owner>.pages.example.com/.

Change the branch

Choose another Branch in the Pages settings and select Save settings. The branch must already exist. Arbinel publishes the site from the new branch immediately.

Publish additional branches

On instances with git-pages nodes, a repository can publish up to five branches besides its main Pages branch. For example, you can preview a development branch before you merge it. The Additional branches section is not available on instances that use StaticHost.

Open Settings > Pages.
Under Additional branches, select a branch.
Select Publish branch.

The branch is served at the site’s address with @<branch> added, such as https://alice.pages.example.com/blog@dev/. It can take a minute before the branch site is reachable. Arbinel publishes the branch again on every push to it.

The following rules apply:

Only branch names made of letters, digits, ., _ and - can be published, because the name becomes part of the address. For example, feature/login cannot be published.
The main Pages branch cannot also be an additional branch.
Custom domains always serve the main branch.
A branch site served under /<repo>@<branch>/ needs /<repo>@<branch>/ as its base path if your generator uses one.

Select Unpublish to remove a branch site. Deleting the branch unpublishes it as well.

Use your own domain

A custom domain serves the main branch of the site at the root of the domain.

Create a DNS record for the domain. For a subdomain such as www.example.org, add a CNAME record that points to the target shown in the Custom domains help text. On instances with git-pages nodes, that is your owner hostname:
```
www.example.org.  CNAME  alice.pages.example.com.
```
An apex domain such as example.org cannot be a CNAME. Use your DNS provider’s ALIAS or ANAME record with the same target, or A and AAAA records with the addresses the instance’s administrators give you.
Open Settings > Pages and add the domain under Custom domains.
Mark one domain as Primary.

The DNS record determines which servers a visitor reaches. The domain in the settings tells the instance which repository the domain belongs to. You need both. Arbinel does not look up the DNS record, so the settings accept a domain before its record exists.

A site can have up to 20 custom domains, and exactly one of them is the primary. The repository’s website field then points to the primary domain. You cannot remove the primary domain until you mark another one as primary. You can remove all custom domains, and the site stays reachable at its managed address.

A domain with characters outside ASCII, such as kolonkės.lt, is stored in its ASCII form, which starts with xn--.

Remove a site

Clear Enabled in the Pages settings and select Save settings. This unpublishes the site and all additional branches, and removes the custom domains. The published content cannot be restored, but your repository is not changed.

Deleting the repository also unpublishes its site.

API

The settings page has an API equivalent under /api/v1/repos/{owner}/{repo}/pages. These endpoints require a token of a repository admin.

Method and path	Purpose
`GET /pages`	Read the Pages settings, the managed address and the domains.
`PUT /pages`	Enable Pages, or change the branch, with `{"branch": "pages"}`.
`DELETE /pages`	Disable Pages.
`GET /pages/status`	Read the state of the latest deployment.
`GET /pages/log`	Read the deployment details.
`PUT /pages/domains`	Replace all custom domains.
`PUT /pages/branches/{branch}`	Publish an additional branch.
`DELETE /pages/branches/{branch}`	Unpublish an additional branch.

The instance’s API reference at /api/swagger describes the request and response bodies.