GitHub Upload Setup Guide

GitHub provides unlimited public repositories and generous private repository storage, making it an excellent choice for version-controlled backup of your tracking data. This guide will help you set up GitHub integration for storing screenshots, HTML archives, and task data with full version history.

Prerequisites

Before setting up GitHub integration, ensure you have:

• GitHub Account: Free or paid GitHub account
• Repository: Dedicated repository for tracking data
• Personal Access Token: Fine-grained or classic token with repo permissions
• Repository Access: Push permissions to the target repository

Step 1: Create a Dedicated Repository

Repository Setup

1. Create Repository: Go to github.com → New repository
2. Repository Name: trackr-bot-data (or your preferred name)
3. Visibility: Choose Private for sensitive data, Public for open sharing
4. Initialize: Add README.md and .gitignore
5. License: Choose appropriate license if making public

Repository Structure

Recommended folder structure for tracking data:

Step 2: Create Personal Access Token

Generate Fine-grained Token (Recommended)

1. GitHub Settings: Go to Settings → Developer settings
2. Personal access tokens: Click "Fine-grained tokens"
3. Generate token: Click "Generate new token"
4. Repository access: Select your tracking data repository
5. Permissions: Grant "Contents" and "Metadata" read/write access
6. Expiration: Set appropriate expiration (90 days recommended)
7. Save token: Copy and securely store the generated token

Alternative: Classic Personal Access Token

If fine-grained tokens aren't available for your account:

1. Classic tokens: Go to "Personal access tokens (classic)"
2. Generate token: Click "Generate new token (classic)"
3. Scopes: Select "repo" for full repository access
4. Note: Add descriptive note (e.g., "Trackr data upload")

Step 3: Configure GitHub Upload Channel

In Trackr Dashboard

1. Navigate to Upload Channels: Go to your Upload Channels
2. Add New Channel: Click "Add New Channel"
3. Select GitHub: Choose "GitHub" from provider options

Required Configuration Fields

Step 4: Test and Validate Configuration

1. Test Upload: Click "Test Configuration" in the channel setup
2. Check Repository: Verify test file appears in your GitHub repository
3. Commit History: Check that commits are properly attributed
4. Save Configuration: If test successful, save the channel

Advanced GitHub Features

Version Control Benefits

• Full History: Every upload is a git commit with timestamps
• Diff Tracking: See exactly what changed in your data over time
• Branching: Create branches for different tracking environments
• Rollback: Easily revert to previous versions of your data

Collaboration Features

• Team Access: Grant repository access to team members
• Issues: Track problems or requests related to your data
• Pull Requests: Review and approve data changes
• Organizations: Manage multiple repositories under organization

Automation Integration

• GitHub Actions: Automate processing of uploaded data
• Webhooks: Trigger external services on data uploads
• API Integration: Build custom tools using GitHub's API
• Third-party Apps: Connect with project management tools

File Organization and Commits

Automatic File Organization

Trackr organizes files with this structure:

Commit Messages

Automatic commit messages include:

• Task Information: Task ID and name
• File Type: Screenshot, HTML archive, or data file
• Timestamp: When the data was collected
• Change Summary: Brief description of what was uploaded

Storage Limits and Pricing

GitHub Storage Limits

• Repository Size: Soft limit of 1GB, hard limit of 100GB
• File Size: 100MB per file (use Git LFS for larger files)
• Public Repositories: Unlimited for free accounts
• Private Repositories: Generous limits, paid plans for more

Git LFS for Large Files

For repositories with many large screenshots:

• Enable LFS: Track large files outside main repository
• Storage Quota: 1GB free, additional storage available
• Bandwidth: 1GB monthly transfer limit
• File Types: Automatically track .png, .jpg, .html files

Troubleshooting Common Issues

Authentication Failures

• Token Permissions: Ensure token has "Contents" write access
• Repository Access: Verify token can access the specified repository
• Token Expiration: Check if token has expired
• Organization Policies: Some organizations restrict token usage

Upload Failures

• File Size: GitHub has 100MB limit per file
• Repository Limits: Check if repository approaching size limits
• Branch Protection: Verify branch allows direct commits
• Network Issues: Temporary connectivity problems

Commit Issues

• Committer Info: Ensure valid name and email are provided
• Branch Permissions: Check write access to target branch
• Merge Conflicts: Handle concurrent uploads appropriately

Best Practices

Repository Management

• Regular Cleanup: Archive old data periodically
• Branch Strategy: Use branches for different environments
• Tagging: Tag important milestones in your tracking data
• Documentation: Maintain README with data structure info

Security and Access

• Minimal Permissions: Grant only necessary repository access
• Token Rotation: Regularly update personal access tokens
• Access Review: Periodically review who has repository access
• Audit Logging: Monitor repository activity logs

GitHub integration provides powerful version control and collaboration features for your tracking data, making it ideal for developers and teams who want comprehensive history tracking and advanced automation capabilities.