forgejo-notification

A command-line tool for managing instance-wide notifications in Forgejo without requiring an instance restart. Well suited for displaying upcoming maintenance and other important notices.

Note

The tool requires building Forgejo from source as template modifications are necessary.

Installation

1. Install forgejo-notification

cd forgejo-notification
go build -o forgejo-notification cmd/main.go

2. Install custom templates and assets

Option A: Automated bootstrapping (recommended)

Note

This has to happen on the server running Forgejo

Use the built-in bootstrap command to automatically install all required files:

export FORGEJO_DATA_DIR=<data dir>

forgejo-notification bootstrap

The bootstrap command will:

• Automatically create necessary directories
• Install all required template and asset files unless they exist (use --force to overwrite)

Option B: Manual installation

Alternatively, place the following files in your Forgejo custom directory:

Templates:

{FORGEJO_DATA_DIR}/custom/templates/custom/

• header_tmpl.html - Loads CSS and JS assets
• extra_navbar_links_tmpl.html - Contains the notification icon and inline script

Assets:

{FORGEJO_DATA_DIR}/custom/public/assets/

• notification-alerts.css - Notification styling
• notification-alerts.js - Notification loading logic

Implementation details

The notification system relies on Forgejo's custom template system. This allows for a static placement of custom notifications in the navbar which is not loaded on-demand and therefore does not cause page flashing.

Usage

forgejo-notification can be run remotely, i.e. from your local machine. To connect to the Forgejo server, it uses the FORGEJO_HOST env var, which should contain a valid SSH hostname for the Forgejo server.

Example:

export FORGEJO_HOST="my-forgejo-server"
forgejo-notification [...]

Create an immediate notification

forgejo-notification add \
  --title "Custom title" \
  --message "Some nice message"

Create a scheduled notification

forgejo-notification add \
  --title "Scheduled Notification" \
  --message "Server maintenance will begin at 2 AM EST and last approximately 2 hours" \
  --start "2025-12-25 02:00 EST"

List active notifications

forgejo-notification list

Clear all notifications

forgejo-notification clear

Command Options

• --data-dir: Path to Forgejo custom data directory
• --start: Optional start time in format "YYYY-MM-DD HH:MM TZ" or "HH:MM TZ" (for scheduled notifications)
• --title: Optional title for the notification
• --message: Description of the notification (required)
• --no-dismiss: Make notification non-dismissible (default: dismissible)

If --start is given, the notification will include a dynamic time based on the users timezone. This argument is useful for broadcasting upcoming notifications.

Timezone formats can be either of <continent/city> (e.g. Europe/London) or use the timezone abbreviation (e.g. UTC or CET).

Important

There is no --end or --duration parameter on purpose. Notifications persist until manually cleared. Include timing details (duration, expected completion) in the message text.

Configuration File Format

The notification-config.json file structure:

{
  "notifications": [
    {
      "id": "notification_1234567890",
      "start": "2025-12-25T02:00:00Z",
      "title": "Database Upgrade",
      "message": "We'll be upgrading our database systems.",
      "dismissible": true
    }
  ]
}