Herald

A GitHub Action that posts to Nostr. Monitors multiple repos for commits and posts scheduled educational content.

Setup

1. Create this repo on GitHub (can be private)

2. Add your Nostr secret key as a repository secret named NOSTR_NSEC

   • Settings > Secrets and variables > Actions > New repository secret
   • Accepts both nsec1... and hex format

3. Copy and configure herald.config.example.json → herald.config.json:

{
  "relays": [
    "wss://relay.damus.io",
    "wss://nos.lol",
    "wss://relay.primal.net"
  ],
  "repos": [
    {
      "owner": "GITHUB_USER_NAME",
      "name": "GITHUB_PROJECT_NAME",
      "projectName": "PROJECT_NAME_FOR_NOTE"
    }
  ]
}

4. Add educational content (optional) as .md files in /notes

5. Enable schedules by uncommenting the schedule lines in:

   • .github/workflows/commits.yml
   • .github/workflows/notes.yml

6. Push to GitHub and the workflows will run on schedule

How It Works

Commit Notifications

Every 3 hours, Herald checks each configured repo for new commits via GitHub API and posts them:

📦 PROJECT_NAME_FOR_NOTE commit

fix: handle edge case in validation

abc1234
https://github.com/GITHUB_USR_NAME/GITHUB_PROJECT_NAME/commit/abc1234

On first run, Herald records the latest commit as a baseline without posting, so you don't spam old commits.

Scheduled Posts

Each run also posts one random note from /notes. Notes cycle without repeats until all have been posted.

Configuration

Adding Repos

Add entries to the repos array:

{
  "owner": "GITHUB_USER_NAME",
  "name": "GITHUB_PROJECT_NAME",
  "projectName": "PROJECT_NAME_FOR_NOTE"
}

• owner + name = GitHub repo path
• projectName = Display name in posts

Changing Schedule

Schedules are commented out by default. Uncomment and edit in .github/workflows/commits.yml or .github/workflows/notes.yml:

schedule:
  - cron: "0 */3 * * *"  # Every 3 hours
  - cron: "0 */6 * * *"  # Every 6 hours
  - cron: "0 12 * * *"   # Once daily at noon UTC

Relays

Configure relays in herald.config.json. Herald broadcasts to all relays in parallel.

Testing

Run either workflow manually with dry run:

1. Go to Actions > Herald - Commits (or Herald - Notes)
2. Click "Run workflow"
3. Check "Dry run"
4. Run

This fetches commits or selects a note but doesn't broadcast.

State

Herald tracks state in .state.json:

• repos: Last seen commit SHA per repo
• posted: List of posted note filenames

This file is auto-committed after each run.