forgejo-notification

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
    }
  ]
}