John

Senior Cloud Engineer & Technical Lead

GitHub Stars Automation

This document explains the automated system for collecting and publishing GitHub repository discoveries.

Overview

The GitHub Stars automation system automatically tracks repositories you star on GitHub and creates formatted blog posts featuring your discoveries. This provides a curated feed of interesting open-source projects and tools.

Features

Architecture

Components

  1. GitHub CLI (gh): Interfaces with GitHub API
  2. Daily Script (scripts/daily-stars.sh): Main automation logic
  3. Quick Script (scripts/quick-stars.sh): Manual collection tool
  4. Jekyll Integration: Generates formatted blog posts

Data Flow

GitHub API → GitHub CLI → Shell Script → JSON Processing → Markdown Generation → Jekyll Post

Setup Instructions

Prerequisites

  1. GitHub Account: With starred repositories
  2. GitHub CLI: Installed and authenticated
  3. Jekyll Site: This repository setup locally

Installation

1. Install GitHub CLI

macOS (Homebrew):

brew install gh

Linux (Debian/Ubuntu):

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

2. Authenticate with GitHub

gh auth login

Choose authentication method:

3. Verify Authentication

gh auth status

Should show:

✓ Logged in to github.com as [username]
✓ Git operations for github.com configured to use https protocol.
✓ Token: *******************

4. Test the Script

# Run daily collection manually
./scripts/daily-stars.sh

Script Details

Daily Stars Script (scripts/daily-stars.sh)

Functionality

Key Features

Duplicate Prevention:

# Extract repo names from yesterday's post
grep -o '\[.*\](' "$YESTERDAY_POST" | sed 's/\[//g' | sed 's/\].*//g' > yesterday-repos.txt

# Filter out repos that were in yesterday's post
comm -23 <(sort all-repo-names.txt) <(sort yesterday-repos.txt) > new-repo-names.txt

JSON Processing:

# Filter JSON to only include new repos
jq --argjson names "$(jq -R -s -c 'split("\n")[:-1]' new-repo-names.txt)" \
   'map(select(.name as $name | $names | index($name)))' \
   all-starred-repos.json > today-starred-repos.json

Content Generation:

# Generate blog post with front matter
cat > "_posts/${TODAY}-daily-github-stars.md" << EOF
---
title: "Daily GitHub Stars: ${TODAY_DISPLAY}"
date: ${TODAY}
layout: post
categories: github-stars
tags: [automation, open-source, github]
---

Today's starred repositories:
EOF

Output Format

Generated posts follow this structure:

---
title: "Daily GitHub Stars: July 26, 2025"
date: 2025-07-26
layout: post
categories: github-stars
tags: [automation, open-source, github]
---

Today's starred repositories:

## 1. [Repository Name](https://github.com/user/repo)

**Author:** username | **Language:** Go | **Stars:** ⭐ 1,234

_Repository description from GitHub._

**Topics:** topic1, topic2, topic3

---

## 2. [Another Repository](https://github.com/user/repo2)

[Continue for each repository...]

Quick Stars Script (scripts/quick-stars.sh)

For manual collection of specific repositories or weekly roundups.

Usage

Manual Execution

# Run daily collection
cd /path/to/johnoct.github.io
./scripts/daily-stars.sh

Automated Execution

# Edit crontab
crontab -e

# Add daily execution at 9:00 AM
0 9 * * * cd /Users/username/code/johnoct.github.io && ./scripts/daily-stars.sh >> /tmp/daily-stars.log 2>&1

Using GitHub Actions (Alternative)

Create .github/workflows/daily-stars.yml:

name: Daily GitHub Stars
on:
  schedule:
    - cron: '0 9 * * *'  # 9 AM UTC daily
  workflow_dispatch:  # Manual trigger

jobs:
  collect-stars:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup GitHub CLI
        run: |
          gh auth login --with-token <<< "$"
      - name: Run daily stars script
        run: ./scripts/daily-stars.sh
      - name: Commit and push
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add _posts/
          git commit -m "Add daily GitHub stars" || exit 0
          git push

Configuration

Script Variables

Edit scripts/daily-stars.sh to customize:

# Number of repositories to fetch
gh api user/starred?per_page=100

# Conservative limit for new installations
head -3 all-starred-repos.json > today-starred-repos.json

# Date formatting
TODAY_DISPLAY=$(date +"%B %d, %Y")

Content Customization

Repository Limit

Change the number of repositories processed:

# Default: processes all new repos
# Conservative: limit to first 5
head -5 all-starred-repos.json > today-starred-repos.json

Metadata Fields

Customize which repository data to include:

NAME=$(echo "$repo" | jq -r '.name // "Unknown"')
DESCRIPTION=$(echo "$repo" | jq -r '.description // "No description provided"')
LANGUAGE=$(echo "$repo" | jq -r '.language // "Unknown"')
STARS=$(echo "$repo" | jq -r '.stars // 0')
TOPICS=$(echo "$repo" | jq -r '.topics // [] | join(", ")')

Troubleshooting

Common Issues

Authentication Errors

# Re-authenticate with GitHub
gh auth logout
gh auth login

No New Repositories

API Rate Limits

File Permissions

# Make script executable
chmod +x scripts/daily-stars.sh
chmod +x scripts/quick-stars.sh

Debugging

Enable Debug Mode

# Add debug output to script
set -x  # Enable debug mode
set +x  # Disable debug mode

Check Generated Files

# Verify JSON output
cat today-starred-repos.json | jq .

# Check generated post
cat "_posts/$(date +%Y-%m-%d)-daily-github-stars.md"

Validate GitHub CLI

# Test API access
gh api user/starred --limit 5

# Check authentication status  
gh auth status

Best Practices

Repository Curation

Content Quality

Automation Reliability

Privacy Considerations

Future Enhancements

Potential Improvements

Integration Opportunities

Automation Status: Once configured, this system requires minimal maintenance while providing consistent, valuable content about open-source discoveries.