Publishing from Silex Desktop¶
Draft — written 21 August 2026, not reviewed yet
Silex Desktop is alpha software, and this page was written alongside the feature it describes. It has not been reviewed. Parts of it are marked as untested below. Tell us what is wrong: the forum or an issue on the Silex repository.
Silex Desktop publishes your website by sending it to a git forge. Your site lives in a repository you own, the forge builds it, and the forge serves it. There is no Silex server in the middle.
Three forges are supported: GitLab, Forgejo (which is what Codeberg runs) and SourceHut.
Before your first publication on Codeberg¶
Codeberg turns Actions off on every new repository. Nothing builds your site until you turn them on, whether the repository is public or private.
Open your repository on Codeberg, go to Settings, then the Units tab, and tick Actions. Publish again after that.
Codeberg also serves pages only from public repositories. A private repository can build your site, but nobody will be able to see it, not even you.
Silex tells you when a build never started and links you to the page where Actions are turned on. You do not have to remember this, but knowing it saves you a wait.
What Silex puts in your repository¶
When you publish, Silex writes four things next to your pages, then commits and pushes them:
| File | Who owns it |
|---|---|
public/ |
Silex. Your published pages, styles and images. |
build.json |
You. Created once with a default, never rewritten. |
build.sh |
Silex. Rebuilt from build.json at every publication. |
| The pipeline file of your forge | Silex, until you say otherwise — see below. |
The pipeline file is .gitlab-ci.yml on GitLab, .forgejo/workflows/pages.yml on Forgejo, and
.build.yml on SourceHut.
Taking over the pipeline file¶
Every pipeline file Silex writes starts with this line:
That line means Silex owns this file and will rewrite it at every publication. Delete the line and the file is yours — Silex will never touch it again.
Do that when you want to change something Silex does not offer as a setting:
- the size of the machine that builds your site (see below),
- how often it runs, for a site that reads a data source,
- extra steps of your own.
You can undo it: put the line back and Silex takes the file over again at the next publication.
Changing the size of the build machine¶
Codeberg lends its build machines for free and asks that each job takes the size it needs, no more.
Silex asks for the smallest one, codeberg-tiny:
Building a small site there took 45 seconds, downloading the build tool included. If your site
grows and the build runs out of time, remove the silexOverwrite line and raise it:
| Label | CPU | Memory | Time allowed |
|---|---|---|---|
codeberg-tiny |
1 | 2 GB | 2 min |
codeberg-small |
2 | 4 GB | 5 min |
codeberg-medium |
4 | 8 GB | 10 min |
Raise timeout-minutes to match the label you pick. The memory figure includes what your build
writes to disk, plus 2 GB of temporary space.
Publishing again without opening Silex¶
Useful when your site reads a CMS or a data source: the content changed, the site did not, and you want a fresh build without opening Silex at all.
GitLab¶
On a schedule — the simplest for a site fed by data. Build → Pipeline schedules → New
schedule, pick how often, target branch main. Your site rebuilds on its own.
From your CMS, with a trigger token. Create one in Settings → CI/CD → Pipeline trigger tokens, then call it from wherever your content lives:
curl --request POST \
--form token=<your trigger token> \
--form ref=main \
"https://gitlab.com/api/v4/projects/<project id>/trigger/pipeline"
With a personal access token, if you already have one:
curl --request POST \
--header "PRIVATE-TOKEN: <your token>" \
"https://gitlab.com/api/v4/projects/<project id>/pipeline?ref=main"
The project id is on your project's home page, under its name.
By hand — Build → Pipelines → Run pipeline.
Forgejo and Codeberg¶
By hand — the Actions tab of your repository, pick the pages workflow, Run workflow.
From your CMS, with a token from Settings → Applications:
curl --request POST \
--header "Authorization: token <your token>" \
--header "Content-Type: application/json" \
--data '{"ref":"main"}' \
"https://codeberg.org/api/v1/repos/<owner>/<repo>/actions/workflows/pages.yml/dispatches"
On a schedule — Silex does not set one up, because it would rebuild your site whether or not
anything changed. To add one, take the workflow file over (remove the silexOverwrite line) and add
a schedule: next to workflow_dispatch::
SourceHut¶
The build manifest names where to clone from, so it can be sent on its own:
Tested
The two commands above for GitLab and Forgejo were run against real repositories while writing this page, and both started a build. The SourceHut one was not — see below.
Where your site ends up¶
Silex shows you the address once the forge has one to give. On the first publication there is nothing to show yet — the build has not finished, so no address exists.
On Codeberg and SourceHut, Silex asks you for the address before publishing: a field appears in the publication window, filled in with the address the forge normally uses. Change it if you have a domain of your own. What you write there is kept with your website and used the next time.
On GitLab there is no field, because glab answers the address by itself.
Setting up the domain itself — the DNS records, the certificate — is done on the forge, not in Silex. Silex links you to the right page after each publication.
When publishing fails¶
The repository has changes Silex does not have. Someone pushed from another machine, or the forge added a file when the repository was created. Silex catches up on its own and publishes. If the changes contradict yours, it stops and says so rather than overwriting anything.
Silex cannot reach the forge. You will see what git said. The usual cause is that the machine has no access to the repository — an SSH key that the forge does not know, or a token that expired.
Codeberg did not build anything. Actions are turned off on the repository. See the top of this page.
Nothing seems to happen after a publication. Only a tag named _silex_… starts a build. If you
tag your repository for your own reasons, that does not publish your site — which is on purpose.