🚀 ActionsCounter

Secure GitHub Actions-powered project analytics with triple storage modes.

Track project usage, downloads, API calls, or any events through simple webhook pings. Choose from GitHub Variables, Database, or Repository storage based on your needs.

⚡ Quick Start (5 Minutes)

1. Fork & Clone

# Fork this repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/ActionsCounter.git
cd ActionsCounter

2. Generate Personal Access Token

📝 Create GitHub Token

Required scopes:

• ✅ repo - Full repository access
• ✅ workflow - Update workflows and trigger actions
• ✅ admin:repo_hook - Repository webhook access
• ✅ read:org - Read organization data

3. Set Repository Secrets

🔐 Configure Secrets

Replace {YOUR_USERNAME} with your GitHub username, then add:

ADMIN_PASSWORD = your_secure_password
PAT_TOKEN = your_personal_access_token_from_step_2

4. Choose Storage Mode

⚙️ Set Variables

STORAGE_MODE = 1

Storage Options:

• 1 = GitHub Variables (48KB, fast, recommended)
• 2 = Database (unlimited, requires PostgreSQL setup)
• 3 = Repository Commits (unlimited, creates git commits)

4. Configure Frontend

Edit frontend/src/main.ts:

const REPO_OWNER = "YOUR_USERNAME";
const REPO_NAME = "ActionsCounter";

5. Enable GitHub Pages

📄 Setup GitHub Pages

Set source to: Deploy from main branch

6. Test Your Setup

🧪 Run Test Workflow

• Click "Run workflow"
• Action: stats
• Click "Run workflow" again

7. Access Your Dashboard

🌐 View Dashboard

Replace {YOUR_USERNAME} with your actual GitHub username in all URLs above.

🎯 Usage

Via GitHub Actions UI

1. Actions tab → Handle Projects (Dual Mode)
2. Choose action (increment, add, list, etc.)
3. Enter project name and password
4. Run workflow

Via Secure Webhook (Recommended)

curl -X POST \
  -H "Authorization: token YOUR_PAT_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  -H "Content-Type: application/json" \
  https://api.github.com/repos/YOUR_USERNAME/ActionsCounter/dispatches \
  -d '{
    "event_type": "increment",
    "client_payload": {
      "project_name": "my-project"
    }
  }'

✅ Secure: No admin password in request - uses repository secrets automatically!

Available Actions

• increment - Add 1 to project count
• decrement - Subtract 1 from project count
• add - Create new project
• remove - Delete project
• set - Set specific count value
• get - View project details
• list - Show all projects
• stats - Display analytics

📊 Storage Modes

Mode	Best For	Capacity	Speed	Setup
GitHub Variables	Most projects	48KB	Very Fast	5 min
Database	High volume	Unlimited	Fast	15 min
Repository Commits	Demos/audit	Unlimited	Slow	10 min

Recommended: Start with GitHub Variables (mode 1), upgrade to Database (mode 2) if you need more capacity.

🔒 Security Features

• Password Protection: All operations require admin password
• Repository Secrets: Sensitive data stored securely in GitHub
• Token Validation: GitHub token authentication
• No Browser Storage: Zero sensitive data in localStorage

📚 Documentation

• 📖 Complete Documentation - Comprehensive guides and references
• 🚀 Fork Setup Guide - Fork-specific setup instructions
• 🎯 Usage Examples - Detailed usage examples and patterns
• 🔑 GitHub Token Scopes - Required Token permissions
• ⚡ Quick Setup - Detailed setup walkthrough
• 🔗 API Reference - All actions and webhook examples
• 🗃️ Storage Modes - Choose the right storage mode

🛠️ Database Setup (Mode 2 Only)

For Database mode, add these secrets:

DB_HOST = your_postgres_host
DB_NAME = your_database_name
DB_PORT = 5432
DB_USER = your_username
DB_PASS = your_password
DB_SCHEMA = myschema

Free PostgreSQL Providers:

• filess.io - 10MB free
• Supabase - 500MB free
• Neon - 512MB free

🌟 Example Use Cases

• Download Tracking: Monitor software/file downloads
• API Analytics: Track API endpoint usage
• Website Metrics: Count page views and interactions
• Project Usage: Monitor tool/library adoption
• Event Tracking: Log application events

🔧 Support & Community

📚 Documentation

• 📖 Complete Setup Guide - Comprehensive documentation
• ❓ FAQ - Quick answers to common questions
• 🛠️ Troubleshooting - Step-by-step problem solving

🤝 Get Help

• 💬 GitHub Discussions - Ask questions, share ideas
• 🐛 Report Bug - Found an issue? Let us know
• ✨ Request Feature - Suggest new features
• 🆘 Support Guide - Comprehensive support information

🌟 Contributing

• 🤝 Contributing Guide - How to contribute to the project
• 👥 Contributors - Meet our amazing contributors

Quick Help:

• "Invalid password" error: Check ADMIN_PASSWORD secret is set correctly
• Analytics not showing: Run any action to generate initial data & verify GitHub Pages is enabled
• Need immediate help? Check our FAQ first!

📄 License

Apache 2.0 License - see LICENSE.md

---

🚀 Ready to start tracking? Fork this repo and follow the Quick Start guide above!