GitHub Reminders Without a Database: Where the Reliability Guarantees Stop
Many developer tools start with a simple need and grow into an unnecessary service: another database, another scheduler, another account, and a recurring bill.
At Caivra Tech LLC we built GitHub Reminders, a free, MIT-licensed GitHub Action for reminders in issue and pull-request discussions. It uses GitHub comments for persistence and GitHub Actions for scheduled delivery rather than introducing a hosted backend.
This article explains the implementation trade-off—and why we explicitly do not promise exactly-once reminders.
Project and installation instructions: https://github.com/caivra-tech/GitHub-reminders
How it works
A collaborator leaves a command in an issue or PR:
/remind in 7 days Revisit this before deleting the branch /remind in 3 hours Check CI again /reminders The configured issue_comment workflow processes the command. A successful creation produces a bot confirmation with a versioned hidden marker containing reminder metadata. Later, a scheduled workflow scans due reminders and attempts delivery by commenting back on the original conversation.
issue/PR comment → command parser → bot confirmation + versioned marker → periodic Actions scan → due reminder check → GitHub mention to creator No external database or separate user service is required. Metadata remains in repository comments, so do not place sensitive information or secrets inside reminder text.
The workflow requests these GitHub token permissions:
permissions: contents: read issues: write pull-requests: write For installation, use the actual versioned example workflow and installation guide. The published maintenance release is v1.0.1; users needing stronger supply-chain pinning can review and pin its release commit 2b98349b0dadd9014e997bcf54197de7755e4001.
The interesting part: persistent state is not a durable queue
This design makes adoption lightweight, but it does not magically make GitHub Actions a real-time scheduler or durable messaging platform.
The provided example coordinates triggers through a named concurrency group with queue: max and cancel-in-progress: false. This serializes runs of that workflow. It has a bounded pending queue of up to 100 runs. If that capacity is reached, incoming runs can be cancelled with no bot acknowledgment.
A scheduled job can also run late or be skipped. That means the delivery contract is best-effort and duplicate-resistant, not guaranteed at-least-once or exactly-once.
An important operational rule follows:
A command left in a comment is not proof the command was processed. Check for the bot's acknowledgment and inspect Actions history if one is absent. Reposting before reconciling may cause duplicate reminders.
A two-write failure worth studying
Delivery crosses two separate GitHub API operations:
- Post the reminder comment.
- Update the original reminder's marker to record delivery.
Those writes are not atomic.
Suppose step 1 succeeds and step 2 fails. If a later scan runs, a trusted delivery marker can help detect the previously posted reminder and repair the source marker without intentionally posting another delivery.
But what if the API call for step 1 times out after the comment may have been committed? A client cannot infer whether it happened from the timeout alone. That is an unknown outcome. GitHub's comments API supplies no transaction that spans delivery and source-state update.
This is why good error handling isn't just a try/catch block. It requires acknowledging that an effect may have happened even if confirmation was lost.
Security and scope boundaries
The project limits command-based cancellation to the reminder's creator, stores versioned metadata, and neutralizes @ symbols in delivered reminder text to avoid surprising third-party pings.
These protections do not mean every privileged workflow sharing a GitHub Actions identity can be independently distinguished. A second differently named reminder workflow is not a supported coordination pattern; two independent scans may evade the intended serialization. The architecture and limitations are documented in the repository.
The action is appropriate for convenient, approximate reminders in a developer workflow. It is not appropriate for safety-critical alerts, contractual deadline guarantees, or workflows that require durable exactly-once command processing.
How to inspect or contribute
- Project README and quick start
- Installation and queue behavior
- Architecture and reliability contract
- Security policy
The public code is licensed under MIT. We welcome focused review of idempotency, trust boundaries, event queues, and timeout recovery. The goal is to make the trade-offs transparent, not to describe a best-effort GitHub reminder as a guaranteed messaging system.
Disclosure: This technical explainer was prepared with AI writing assistance and reviewed against the project's public README, installation guide, and architecture documentation. It describes documented design and limitations; it is not an independently executed benchmark or a fresh live scheduled-delivery certification.