Forgejo

Publish static sites

It is possible to easily configure a Forgejo repository to be built and published on any unused subdomain of frog-collective.com every time a commit is pushed to it. To do so, you must configure a web hook in the repository so that push events can trigger the build and publishing of your static web pages.

Configuration

You must have the administration rights on the repository you want to publish. To publish a repository, you must first configure a web hook on it.

• If your repository is in an organization, go to the Settings page of your Organization, and check that Public is selected in the Visibilty section. Don't forget to click Update Settings if you change the visibility.
• Go to the Settings page of the repository you want to publish.
• Select the Repository tab.
• Check that the checkbox Make the repository private is unchecked. If not, uncheck it and click Update Settings.
• Now select the Webhooks tab.
• Click Add Webhook and choose the Forgejo hook type.
• Fill the form :
  • Target URL : enter https://fsp.frog-collective.com (FSP stands for Forgejo Static Pages)
  • HTTP Method: select POST
  • Post content type: select application/json
  • Secret: For now, you must ask the secret to someone who knows it. Write on the IT channel on Discord, or send a mail to admin@collectivit.org
    
  • Trigger On: select push events
  • Branch filter: you probably want to enter main here.
  • Authorization header: Leave blank
• Click Add webhook

Now that the web hook is configured, add a file at the root of your repository named .static-pages.yml with the following content  :

site_name: peter.frog-collective.com # The hostname where the website will be available
build_command: nox -r -s build # The command to run to build your pages
build_directory: build # The folder relative to the repository root where the pages are, once built

Add it, commit on the branch you entered in the Branch filter field when configuring the web hook, and push. After a while, your website should appear at the configured address.

Never leak the web hook secret : as the pages are built by running a custom command, having access to this secret means being able to run arbitrary code on the CollectivIT production servers. For the same reason, be cautious when you configure your build commands.

The environment in which the build is launched on the static pages server is limited. You can use bash, python and nox. Don't expect other software to be available, as it is subject to change without notice. If you have other build dependencies, nox is a good way to go to create virtual environments to install them, and nodeenv can be used to create nodejs virtualenvs if you need npm.

For now it is not possible to build different branches to different domains, but it could be easily added, fill a ticket on https://git.frog-collective.com/collectivit/collectivit/issues if you want that.

For now, only public repositories can be published. This limitation will be avoided in the future by creating a specific user for the page build service : check https://git.frog-collective.com/collectivit/collectivit/issues/81

Troubleshooting

If your website doesn't go online in a reasonable amount of time after you pushed, first, check that the hook is sent and received :

• Go to the Settings page of your repository
• On the Webhook tab, click on the web hook you created (https://fsp.frog-collective.com)
• At the bottom of the page, there is a Recent delivery panel, that should contains the last events sent by Forgejo.
  • If there are no events, check that the Filter branch field is correctly filled.
  • If you see some event that failed, click and them and inspect the Response tab : the Body section can contain useful information on what's going wrong (bad hook secret...).

If the Body section contains {"status": "queued"} but nothing gets online, the hook is received, but the build and publish fail at some point. In this case :

• Double check the command you configured in the build_command field of your .static-pages.yml
• Double check that the configured build command runs correctly on your machine.
• Check that the build_directory is also correct.
• If you pushed multiple commits in a short amount of time, the issue could be a manifestation of https://git.frog-collective.com/collectivit/collectivit/issues/80: wait a moment after the last push, and click the Retry button (Replay this web hook) of the last (topmost) event only once, and wait without pushing or sending events.
• If it's still not working, I'm sorry to tell you that there is nothing to check the build log on the remote machine for now, so ping the #it channel on the Discord server, or send a mail to admin@collectivit.org asking for help.