# Forgejo

## [![forgejo-logo.png](https://doc.frog-collective.com/uploads/images/gallery/2024-06/scaled-1680-/forgejo-logo.png)](https://doc.frog-collective.com/uploads/images/gallery/2024-06/forgejo-logo.png)

### 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`](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 :

```yaml
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.

<p class="callout warning">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.</p>

<p class="callout info">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.</p>

<p class="callout info">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](https://git.frog-collective.com/collectivit/collectivit/issues) if you want that.</p>

<p class="callout info">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](https://git.frog-collective.com/collectivit/collectivit/issues/81)  
</p>

#### 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](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.