# mod\_site\_update

Source: https://zotonic.com/docs/2207/mod_site_update

URI: https://zotonic.com/id/2207

Language: en



This module pulls updates of a site‘s code from a remote version control system. The supported version control systems are git and mercurial.

After enabling this module you will see a **Deployment** page in the System menu in the admin.

This button is only available to users with the *use.mod\_site\_update* right. It opens a preview of the current commit and incoming remote history. Fetching this preview does not change checked-out files; deployment starts only after pressing **Deploy**.

Deploy controls show a node-wide **Deployment running** indicator, including updates started from another page or the CLI. The retained MQTT topic `$SYS/status/code-update` (under the extensible `$SYS/status/` namespace) carries the sanitized node-wide coordinator state in the shared MQTT pool. Indicators subscribe to changes without polling; new pages receive the current state immediately. The topic follows the coordinator's active deployment state, so failed or completed deployments are not marked running. Snapshots use two-hour retention and are refreshed on state changes, coordinator restart and site startup. Rendering an indicator also reads the coordinator directly, so it does not depend on an unexpired snapshot. Subscribers need administrator or `use mod_site_update` permission; no repository paths or failure terms are published.

**Reset** lists the site's uncommitted changes before offering **Undo all local changes**. This restores tracked files and removes non-ignored untracked files throughout the repository. Local commits and nested repositories are preserved. Reset rebuilds and activates the code before releasing a failed deployment barrier; a failed rebuild keeps the barrier closed. Deployment previews remain available after failures so deployment can also be retried directly.

The update uses the same deployment barrier as `bin/zotonic deploy`: restore the tracked Git lock file, pull code, compile and activate the updated modules before allowing schema upgrades. File changes are buffered until activation completes, then caches and template indexes are refreshed.

This update of the system can take a while.

Webhook
-------

In GitHub and other systems it is possible to set a *webhook* that is called when new updates are pushed to the repository.

In System > Modules there is a *Config* button next to the mod\_site\_update module. Click this and configure a secure token to be passed to the webhook.

The URL for GitHub et al is:

```erlang
https://yoursite.test/api/model/site_update/post/webhook/<token>
```

Where `<token>` should be replaced with your configured token.

The token is saved in the config key `mod_site_update.webhook_token`.

Ensure that the external system performs a HTTP POST to the webhook, the posted body is dropped.

Zotonic status site
-------------------

The `mod_site_update` module is also used by the zotonic status site.

Here the module adds buttons to update sites and a button to update the complete Zotonic system.

Site updates get their datamodel fixed by automatic restarts of modules, ensure that you increment the `-mod_schema(...)` version number.

Zotonic updates are a bit more complicated. Small updates will be fine. Large updates that also change the datamodel or add new Erlang dependencies need more compilation and a system restart. So be careful with using this update button.

Accepted Events
---------------

The Modules page renders deployment-button placeholders without discovering repositories. A single `module_deployment_buttons` postback starts a background lookup and fills the applicable rows through page actions. Repository discovery retains its short cache; preview and deployment still resolve the repository and check permissions again.

Delegate callbacks:

- `event/2` with `postback` messages: `make`, `module_deployment_buttons`, `vcs_up` (open dialog), `vcs_preview` (fetch preview), `vcs_deploy` (confirmation), `vcs_reset` (list local changes), `vcs_reset_confirm` (discard and rebuild).

License: 

Attribution: 

Related resources: https://zotonic.com/api/agent/related/2207?language=en


## API access

- [API help](<https://zotonic.com/api-help>)
- [OpenAPI specification](<https://zotonic.com/openapi.json>)
- [This resource as JSON](<https://zotonic.com/api/agent/resource/2207?language=en>)
