{"id":43255952,"url":"https://github.com/iamgerwin/sure-daily-github","last_synced_at":"2026-02-01T13:33:08.638Z","repository":{"id":320662080,"uuid":"1073589269","full_name":"iamgerwin/sure-daily-github","owner":"iamgerwin","description":"Lean automation for daily GitHub commits - VPS optimized","archived":false,"fork":false,"pushed_at":"2025-12-17T17:47:23.000Z","size":89,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-21T06:13:26.207Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iamgerwin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-10T10:28:00.000Z","updated_at":"2025-12-17T17:47:27.000Z","dependencies_parsed_at":"2025-10-25T05:44:29.526Z","dependency_job_id":null,"html_url":"https://github.com/iamgerwin/sure-daily-github","commit_stats":null,"previous_names":["iamgerwin/sure-daily-github"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/iamgerwin/sure-daily-github","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Fsure-daily-github","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Fsure-daily-github/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Fsure-daily-github/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Fsure-daily-github/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iamgerwin","download_url":"https://codeload.github.com/iamgerwin/sure-daily-github/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Fsure-daily-github/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28979126,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T12:13:08.691Z","status":"ssl_error","status_checked_at":"2026-02-01T12:13:08.356Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-01T13:33:08.018Z","updated_at":"2026-02-01T13:33:08.627Z","avatar_url":"https://github.com/iamgerwin.png","language":"JavaScript","readme":"# Sure Daily GitHub\n\n\u003e Lean automation for daily GitHub commits - VPS optimized\n\n A minimal Node.js automation tool that ensures consistent GitHub activity with configurable daily commit targets, optional randomization, and multi-repository selection strategies. Built specifically for low-resource VPS deployment.\n\n## Features\n\n- 🚀 **Lightweight** - Minimal dependencies, \u003c50MB memory footprint\n- 🔒 **Secure** - Environment-based token management, input validation\n- ⏰ **Scheduled** - Cron-based automation with timezone support\n- 📊 **Trackable** - State management to avoid duplicate commits\n- 🧪 **Testable** - Dry-run mode for safe testing\n- 🖥️ **VPS-Ready** - Systemd service included for production deployment\n- 🎲 **Randomized Activity** - Range-based counts with time-based variations\n- 🗂️ **Multi-Repo Selection** - Sequential, random, weighted, and round-robin strategies\n - 🧮 **Stateful Limits** - Hourly/Daily/Weekly counters with timezone-aware resets\n\n## Quick Start\n\n### 1. Installation\n\n```bash\n# Clone the repository\ngit clone \u003cyour-repo-url\u003e\ncd sure-daily-github\n\n# Install dependencies\nnpm install\n\n# Make CLI executable (if needed)\nchmod +x src/cli.js\n\n# Link CLI globally (optional)\nnpm link\n```\n\n### 2. Configuration\n\n```bash\n# Create example configuration\nnode src/cli.js init\n\n# Edit the configuration\nnano config/config.yaml\n```\n\nUpdate `config/config.yaml` with your repository details (number or range-based `dailyTarget`):\n\n```yaml\nrepositories:\n  - owner: \"yourusername\"\n    repo: \"your-repo\"\n    enabled: true\n    branch: \"main\"\n    # Fixed number or range\n    # dailyTarget: 1\n    dailyTarget:\n      min: 3\n      max: 7\n    path: \"daily-updates\"\n    commitMessage: \"docs: daily update ${date}\"\n```\n\n### 3. GitHub Token Setup\n\nCreate a GitHub Personal Access Token:\n\n1. Go to https://github.com/settings/tokens\n2. Click \"Generate new token\" → \"Fine-grained tokens\"\n3. Set permissions: `contents:write`\n4. Copy the token\n\nSet the environment variable:\n\n```bash\n# Create .env file\ncp .env.example .env\n\n# Edit and add your token\necho \"GITHUB_TOKEN=ghp_your_token_here\" \u003e .env\n```\n\n### 4. Test\n\n```bash\n# Validate configuration (pretty prints ranges/randomization)\nnode src/cli.js validate\n\n# Test with dry-run (no actual writes)\nnode src/cli.js run --dry-run\n\n# Run unit tests\nnpm test\n\n# Check repository status\nnode src/cli.js status\n```\n\n### 5. Run\n\n```bash\n# Run once manually\nnode src/cli.js run\n\n# Start scheduler (keeps running)\nnode src/cli.js start\n```\n\n## CLI Commands\n\n```bash\nsure-daily-github init              # Create example configuration\nsure-daily-github validate          # Validate configuration file\nsure-daily-github run [--dry-run]   # Run once (manual trigger)\nsure-daily-github start             # Start scheduler (daemon mode)\nsure-daily-github status            # Check repository status\nsure-daily-github --help            # Show all commands\n```\n\n## VPS Deployment\n\n### Option 1: Systemd Service (Recommended)\n\nCreate a systemd service for automatic startup and management.\n\n```bash\n# Copy service file\nsudo cp deployment/sure-daily-github.service /etc/systemd/system/\n\n# Edit service file with your paths\nsudo nano /etc/systemd/system/sure-daily-github.service\n\n# Update these lines:\n#   WorkingDirectory=/path/to/sure-daily-github\n#   Environment=\"GITHUB_TOKEN=your_token\"\n\n# Enable and start service\nsudo systemctl daemon-reload\nsudo systemctl enable sure-daily-github\nsudo systemctl start sure-daily-github\n\n# Check status\nsudo systemctl status sure-daily-github\n\n# View logs\nsudo journalctl -u sure-daily-github -f\n```\n\n### Option 2: PM2 Process Manager\n\n```bash\n# Install PM2 globally\nnpm install -g pm2\n\n# Start with PM2\npm2 start src/cli.js --name \"sure-daily-github\" -- start\n\n# Save PM2 process list\npm2 save\n\n# Setup PM2 startup script\npm2 startup\n```\n\n### Option 3: Cron (Simplest)\n\n```bash\n# Edit crontab\ncrontab -e\n\n# Add entry to run every 6 hours\n0 */6 * * * cd /path/to/sure-daily-github \u0026\u0026 /usr/bin/node src/cli.js run \u003e\u003e /var/log/sure-daily-github.log 2\u003e\u00261\n```\n\n## Configuration Reference\n\n### General Settings\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `timezone` | string | `UTC` | Default timezone |\n| `dailyTarget` | number or range | `1` | Fixed count or `{ min, max }` (1-100) |\n| `mode` | string | `commit` | Operation mode: `commit` or `issue` |\n| `dryRun` | boolean | `false` | Test mode without actual commits |\n\n#### Randomization (Optional)\n\n```yaml\nrandomization:\n  enabled: true\n  issueCount: { min: 12, max: 50 }\n  timeVariations:\n    enabled: true\n    hourly: { min: 1, max: 5 }\n    daily: { min: 10, max: 30 }\n    weekly: { min: 50, max: 150 }\n```\n\n#### Repository Selection (Optional)\n\n```yaml\nrepositorySelection:\n  strategy: sequential   # sequential | random | weighted | round-robin\n  randomizeOrder: false\n  maxPerExecution: null  # number or null\n```\n\n### Schedule Settings\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `enabled` | boolean | `false` | Enable automatic scheduling |\n| `cron` | string | `\"0 */6 * * *\"` | Cron expression |\n| `timezone` | string | `UTC` | Scheduler timezone |\n\n### Repository Settings\n\n| Option | Type | Required | Description |\n|--------|------|----------|-------------|\n| `owner` | string | ✅ | GitHub username/organization |\n| `repo` | string | ✅ | Repository name |\n| `enabled` | boolean | ❌ | Enable/disable repository (default: true) |\n| `branch` | string | ❌ | Target branch (default: main) |\n| `dailyTarget` | number or range | ❌ | Override global target |\n| `path` | string | ❌ | Path for commits (default: daily-updates) |\n| `commitMessage` | string | ❌ | Commit message template |\n| `labels` | array | ❌ | Labels to apply (issue mode) |\n| `weight` | number | ❌ | Weight for weighted selection (default: 1) |\n\n\u003e See docs/RANDOMIZATION.md for detailed examples.\n\n## State Management\n\n- Persistent counters per repository with hourly/daily/weekly windows\n- Timezone-aware resets using `general.timezone` (default `UTC`)\n- Graceful fallbacks on state corruption (automatic `.bak` backup)\n- Override storage path with `SDG_STATE_FILE`\n\nSee docs/STATE.md for details.\n\n## Backward Compatibility\n\nThe original behavior remains the default when advanced features are disabled:\n- Sequential processing of all enabled repositories\n- Single issue/commit per run per repository\n- `dailyTarget` can remain a simple number\n- If the state file is missing/corrupted, the tool falls back safely and continues\n\nExisting configurations continue to work without changes. Optional blocks like `randomization` and `repositorySelection` enhance behavior only when provided.\n\n## Security Best Practices\n\n- ✅ Never commit `.env` files\n- ✅ Use fine-grained tokens with minimum permissions (`contents:write`)\n- ✅ Rotate tokens regularly (set expiration dates)\n- ✅ Use environment variables for all secrets\n- ✅ Validate all configuration inputs\n- ✅ Enable rate limiting (built-in)\n- ✅ Review logs regularly\n\n## Troubleshooting\n\n### Authentication Failed\n\n```bash\n# Check token format\necho $GITHUB_TOKEN\n\n# Should start with ghp_ or github_pat_\n\n# Test authentication\nnode src/cli.js validate\n```\n\n### Rate Limit Issues\n\nThe tool includes automatic rate limiting and retry logic. If you hit rate limits:\n\n- Reduce `dailyTarget` values\n- Increase time between scheduled runs\n- Check remaining rate limit: logs will show current limits\n\n### Permission Errors\n\nEnsure your GitHub token has:\n- `contents:write` permission for commits\n- Access to target repositories\n\n## Resource Usage\n\nTypical resource usage on VPS:\n- **Memory**: 30-50 MB\n- **CPU**: \u003c1% (idle), 2-5% (during execution)\n- **Disk**: \u003c100 MB including node_modules\n- **Network**: Minimal (only GitHub API calls)\n\nRecommended VPS specs:\n- 512 MB RAM minimum\n- 1 vCPU\n- 10 GB disk space\n\n## Development\n\n```bash\n# Run tests (if implemented)\nnpm test\n\n# Run with debug logging\nLOG_LEVEL=debug node src/cli.js run\n\n# Format code (if using prettier)\nnpm run format\n\n# Lint code (if using eslint)\nnpm run lint\n```\n\n## Project Structure\n\n```\nsure-daily-github/\n├── src/\n│   ├── cli.js              # CLI entry point\n│   ├── core/\n│   │   ├── scheduler.js    # Cron scheduling\n│   │   └── executor.js     # Main execution logic\n│   ├── github/\n│   │   ├── client.js       # GitHub API client\n│   │   └── commit-handler.js\n│   ├── config/\n│   │   └── loader.js       # Configuration loader\n│   └── utils/\n│       ├── logger.js       # Logging utility\n│       └── state.js        # State management\n├── config/\n│   └── config.example.yaml\n├── deployment/\n│   └── sure-daily-github.service\n├── .env.example\n└── package.json\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please ensure:\n- Code follows existing patterns\n- Security best practices are maintained\n- Documentation is updated\n- No credentials in commits\n\n## Support\n\nFor issues, questions, or contributions:\n- Open an issue on GitHub\n- Check logs in `./logs/` directory\n- Review configuration with `validate` command\n\n## Release Notes\n\n### Latest Release: v1.5.1 (2025-12-24)\n\n#### New Features\n- **Systemd Service Management**: Automated process lifecycle management with auto-restart capability\n- **Health Monitoring**: Cron-based health checks that run every 30 minutes and auto-recover from failures\n- **Status Verification Tools**: Quick diagnostics scripts for monitoring service health and status\n- **Comprehensive Documentation**: Professional setup and troubleshooting guide (docs/SCHEDULER_SETUP.md)\n\n#### What This Fixes\n- Scheduler process hanging without any restart mechanism\n- Missing days of GitHub contributions due to service outages\n- Lack of monitoring and diagnostics tools\n- Difficult manual recovery procedures\n\n#### Key Improvements\n- ✅ Automatic restart on crash (10-second delay)\n- ✅ Memory limit enforcement (512MB)\n- ✅ Health monitoring every 30 minutes\n- ✅ Boot-time service persistence\n- ✅ Comprehensive logging and status tracking\n\nFor detailed release information, see [CHANGELOG.md](./CHANGELOG.md)\n\n## Deployment\n\n### Production Deployment with Systemd\n\nFor production environments, use the included systemd service:\n\n```bash\n# Copy the service file\nsudo cp deployment/sure-daily-github.service /etc/systemd/system/\n\n# Enable and start the service\nsudo systemctl daemon-reload\nsudo systemctl enable sure-daily-github\nsudo systemctl start sure-daily-github\n\n# Add health check to crontab\n*/30 * * * * /opt/sure-daily-github/scripts/health-check.sh\n```\n\n### Verify Installation\n\n```bash\n# Check service status\nsystemctl status sure-daily-github\n\n# Run status verification\n/opt/sure-daily-github/scripts/verify-status.sh\n```\n\n### Documentation\n\n- **Setup Guide**: See [docs/SCHEDULER_SETUP.md](./docs/SCHEDULER_SETUP.md)\n- **Troubleshooting**: See [docs/SCHEDULER_SETUP.md#troubleshooting](./docs/SCHEDULER_SETUP.md)\n- **Version History**: See [CHANGELOG.md](./CHANGELOG.md)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamgerwin%2Fsure-daily-github","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiamgerwin%2Fsure-daily-github","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamgerwin%2Fsure-daily-github/lists"}