Automation

Automated data collection using GitHub Actions

Overview

The F1 Stats Archive uses GitHub Actions to automatically update race data on a scheduled basis. This ensures the archive stays current with the latest Formula 1 statistics from the Ergast API.

GitHub Actions Workflow

The automation is configured in .github/workflows/run.yml:

name: Update Stats

on:
  schedule:
    - cron: '59 23 26 10 *'  # Run every Monday at midnight UTC
  workflow_dispatch:  # Allow manual triggering

jobs:
  update-team-points:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Run
        run: |
          python driver_points.py
          python events.py
          python laptimes.py
          python pitstops.py
          python quali_results.py
          python results.py
          python sprint_results.py
          python team_points.py

      - name: Commit and push if changes
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
          git add .
          git diff --quiet && git diff --staged --quiet || (git commit -m "Update team points data" && git push)

How It Works

1. Scheduled Execution

The workflow runs automatically based on the cron schedule:

schedule:
  - cron: '59 23 26 10 *'  # Custom schedule

The cron expression can be modified to run at different intervals. For example, 0 0 * * 1 would run every Monday at midnight UTC.

2. Data Collection Scripts

The workflow executes all Python scripts sequentially:

• driver_points.py - Fetches driver championship standings
• events.py - Retrieves race schedule and event information
• laptimes.py - Collects all lap times for races
• pitstops.py - Gathers pit stop data
• quali_results.py - Gets qualifying session results
• results.py - Fetches race results
• sprint_results.py - Collects sprint race results
• team_points.py - Retrieves constructor championship standings

Each script:

• Respects Ergast API rate limits
• Creates the appropriate directory structure
• Saves data as JSON files
• Handles errors and retries gracefully

3. Automatic Commits

If new data is fetched, the workflow automatically:

1. Configures Git with the GitHub Actions bot identity
2. Stages all changes
3. Creates a commit with the message “Update team points data”
4. Pushes changes back to the repository

git config --local user.email "github-actions[bot]@users.noreply.github.com"
git config --local user.name "github-actions[bot]"
git add .
git diff --quiet && git diff --staged --quiet || (git commit -m "Update team points data" && git push)

The workflow only creates a commit if there are actual changes to the data.

Manual Triggering

You can manually trigger the workflow using the GitHub UI:

1. Go to your repository on GitHub
2. Click the Actions tab
3. Select the Update Stats workflow
4. Click Run workflow
5. Choose the branch and click Run workflow

Alternatively, use the GitHub CLI:

gh workflow run run.yml

Configuring for Your Own Use

1. Fork the Repository

gh repo fork your-username/f1-stats-archive

2. Adjust the Schedule

Edit .github/workflows/run.yml to change when data updates occur:

schedule:
  - cron: '0 2 * * *'  # Run daily at 2 AM UTC
  # - cron: '0 */6 * * *'  # Run every 6 hours
  # - cron: '0 0 * * 0'  # Run weekly on Sundays

3. Customize Data Collection

Modify the scripts to collect specific data:

Example: Only collect data for recent seasons

Edit the year range in each script:

# In events.py, results.py, etc.
start_year = 2020  # Change from 1950
end_year = 2024

Example: Focus on specific race rounds

# In driver_points.py
if __name__ == "__main__":
    # Only process specific rounds
    for round_num in range(1, 24):  # All rounds
        process_round(2024, round_num)

4. Set Up Repository Permissions

Ensure GitHub Actions has permission to commit:

1. Go to Settings > Actions > General
2. Scroll to Workflow permissions
3. Select Read and write permissions
4. Check Allow GitHub Actions to create and approve pull requests
5. Click Save

Without write permissions, the workflow can fetch data but won’t be able to commit changes back to the repository.

Monitoring Workflow Runs

View Run History

Check the status of past workflow runs:

gh run list --workflow=run.yml

View Run Logs

gh run view <run-id> --log

Check for Failures

The workflow may fail if:

• The Ergast API is unavailable
• Rate limits are exceeded
• Network connectivity issues occur
• Data format changes unexpectedly

Check the Actions tab on GitHub for detailed error logs.

Best Practices

Optimize for Rate Limits

If you’re collecting large amounts of data:

# Increase delays between requests
time.sleep(0.5)  # Instead of 0.25 seconds

Enable Notifications

Get notified when workflows fail:

1. Go to your GitHub notification settings
2. Enable Actions notifications
3. Choose email or web notifications

Use Workflow Artifacts

Store logs or intermediate data:

- name: Upload logs
  if: always()
  uses: actions/upload-artifact@v3
  with:
    name: fetch-logs
    path: '*.log'

Troubleshooting

Workflow Not Running on Schedule

• Verify the cron syntax is correct
• Ensure the workflow file is in the default branch
• Check that Actions are enabled for your repository

Commits Not Pushing

• Verify repository permissions (see setup section)
• Check for branch protection rules that might block automated commits
• Ensure the GitHub Actions bot has write access

Rate Limit Errors

If you see 429 errors:

• Reduce the frequency of scheduled runs
• Increase delays in the Python scripts
• Focus on collecting only recent data

See the Rate Limiting documentation for more details.