donetick-notifier/README.md

donetick-notifier

AI disclaimer: AI was used solely for creating this README, the Gitea pipelines, and the base of the webhook consumer.

A PowerShell-based notifier and webhook consumer for Donetick chores.

The project now has two runtime paths:

• A scheduled notifier that checks the Donetick external API for chores and sends Apprise-compatible summary notifications for overdue and due-today tasks.
• A webhook consumer that listens on port 8080, accepts Donetick webhook payloads, and turns them into Apprise notifications.

Features

• Fetches chores from https://<DONETICKHOST>:<DONETICKPORT>/eapi/v1/chore.
• Authenticates to Donetick with the secretkey header.
• Sends one notification for overdue chores when any exist.
• Sends one notification for chores due today when any exist.
• Accepts webhook events for task.completed, task.reminder, and task.created.
• Falls back to a generic notification for unknown webhook event types.
• Runs the scheduler and webhook listener together in the Docker container.
• Includes Gitea pipelines for Docker image publishing and security scanning.

How It Runs

The container entrypoint is main.sh.

• supercronic runs Start-DoneTickNotifier.ps1 on the schedule defined by JOB_SCHEDULE.
• Start-DoneTickConsumer.ps1 runs in the foreground and listens on http://+:8080/.

The notifier and consumer both use AppriseNotification.psm1 to send messages to the configured Apprise webhook.

Configuration

All configuration is provided through environment variables.

Variable	Required	Description
DONETICKHOST	Yes	Donetick host name or IP address. Do not include https://.
DONETICKPORT	Yes	Donetick HTTPS port.
DONETICKAPIKEY	Yes	Donetick external API key. Sent as the secretkey header.
APPRISEWEBHOOKURL	Yes	Apprise webhook URL that accepts notification posts.
APPRISEWEBHOOKTAG	Yes	Apprise tag value to include with each notification.
JOB_SCHEDULE	Yes for Docker	Cron expression used by the container scheduler, such as 0 8,17 * * *.
TZ	No	Container timezone, such as America/Chicago. Recommended so notification hours match your local time.

Docker

The published image is docker.io/blinkfink182/donetick-notifier.

Run

docker run -d \
  --name donetick-notifier \
  -p 8080:8080 \
  -e DONETICKHOST=host.docker.internal \
  -e DONETICKPORT=8787 \
  -e DONETICKAPIKEY=your-donetick-api-key \
  -e APPRISEWEBHOOKURL=https://apprise.example.com/notify/config \
  -e APPRISEWEBHOOKTAG=all \
  -e JOB_SCHEDULE="0 8,17 * * *" \
  -e TZ=America/Chicago \
  docker.io/blinkfink182/donetick-notifier

Docker Compose

services:
  donetick-notifier:
    container_name: donetick-notifier
    image: docker.io/blinkfink182/donetick-notifier
    ports:
      - 8080:8080
    environment:
      - DONETICKHOST=host.docker.internal
      - DONETICKPORT=8787
      - DONETICKAPIKEY=your-donetick-api-key
      - APPRISEWEBHOOKURL=https://apprise.example.com/notify/config
      - APPRISEWEBHOOKTAG=all
      - JOB_SCHEDULE=0 8,17 * * *
      - TZ=America/Chicago

Run it with:

docker compose up -d

If Donetick and Apprise are on the same Docker network, use service names instead of host.docker.internal.

services:
  donetick-notifier:
    image: docker.io/blinkfink182/donetick-notifier
    ports:
      - 8080:8080
    environment:
      - DONETICKHOST=donetick
      - DONETICKPORT=8787
      - DONETICKAPIKEY=your-donetick-api-key
      - APPRISEWEBHOOKURL=http://apprise:8000/notify/config
      - APPRISEWEBHOOKTAG=all
      - JOB_SCHEDULE=0 8,17 * * *
      - TZ=America/Chicago

Build Locally

docker build -t donetick-notifier .

docker run -d \
  --name donetick-notifier \
  -p 8080:8080 \
  -e DONETICKHOST=host.docker.internal \
  -e DONETICKPORT=8787 \
  -e DONETICKAPIKEY=your-donetick-api-key \
  -e APPRISEWEBHOOKURL=https://apprise.example.com/notify/config \
  -e APPRISEWEBHOOKTAG=all \
  -e JOB_SCHEDULE="0 8,17 * * *" \
  -e TZ=America/Chicago \
  donetick-notifier

Run Without Docker

PowerShell 7 or newer is recommended.

Scheduled notifier:

$env:DONETICKHOST = "donetick.example.com"
$env:DONETICKPORT = "8787"
$env:DONETICKAPIKEY = "your-donetick-api-key"
$env:APPRISEWEBHOOKURL = "https://apprise.example.com/notify/config"
$env:APPRISEWEBHOOKTAG = "all"

pwsh ./Start-DoneTickNotifier.ps1

Webhook consumer:

$env:APPRISEWEBHOOKURL = "https://apprise.example.com/notify/config"
$env:APPRISEWEBHOOKTAG = "all"

pwsh ./Start-DoneTickConsumer.ps1

The consumer listens on port 8080 by default. Stop either script with Ctrl+C when running interactively.

CI/CD

This repository includes Gitea workflows for:

• Building and pushing the Docker image on manual dispatch.
• Tagging images as latest for main, as the ref name for v* tags, and as test for everything else.
• Running security checks with Gitleaks, Semgrep, and Trivy.
• Creating Gitea issues for security findings when GITEA_TOKEN is configured.
• Sending Apprise notifications for Docker build success or failure.

The security workflow runs on pushes, pull requests, and manual dispatch. On push, it also builds the image so Trivy can scan the resulting container.

API References

The Donetick/ directory contains request examples and collection metadata used to document and exercise the Donetick API while developing the notifier.