@gurupanguji

Self-Hosted Social Runner Design

Context

The Publish Social Snippets workflow was paused because it was consuming too many GitHub Actions minutes on ubuntu-latest. The publisher itself is already local Python code and already reads all platform secrets from the job environment, so the cheaper fix is to move the job onto a self-hosted runner instead of rewriting the publishing path.

Goal

Run the existing social publishing workflow on a self-hosted macOS GitHub Actions runner while preserving the current publisher script, snippet format, and secret handling.

Scope

• Restore the scheduled trigger for publish_social.yml.
• Change the job to run on a self-hosted macOS runner.
• Keep manual dispatch available.
• Add a short operational document that explains how to register and maintain the runner.
• Update the repo README so the new runner note is easy to find.

Non-Goals

• Do not change scripts/publish_social.py.
• Do not change snippet file format or published-state tracking.
• Do not introduce a separate local daemon or launchd service in this change.
• Do not move secrets out of GitHub Environment variables.

Design

The workflow stays in GitHub Actions, but the compute moves to a Mac that the user owns and registers as a self-hosted runner. The job can keep using the existing environment secrets, because those secrets are injected by GitHub at runtime, not stored in the runner.

The workflow should use a broad macOS runner selector such as self-hosted plus macOS so it can run on the user’s registered machine without baking in a machine-specific hostname. The existing workflow_dispatch inputs stay intact for manual runs. The schedule should be restored to the previous daily cadence so new published snippets are picked up automatically.

Operational Notes

• The runner machine must stay online during the scheduled window.
• The runner must have Python available and be able to clone the repository.
• The workflow should continue to use contents: write and pull-requests: write because the publisher still marks snippets as published and opens a metadata PR.
• If the runner goes offline, the workflow will queue until a matching runner returns or fail if no runner is available.

File Changes

• Modify .github/workflows/publish_social.yml
• Add docs/self-hosted-social-runner.md
• Modify README.md

Acceptance Criteria

1. publish_social.yml runs on a self-hosted macOS runner instead of ubuntu-latest.
2. The daily schedule is restored.
3. Manual workflow_dispatch runs still work.
4. The repository has a short doc that explains how to register and maintain the runner.
5. The README points readers to the runner note.