GitHub Actions Workflows

AIWebFeeds uses an extensive suite of GitHub Actions workflows to ensure code quality, automate testing, and streamline development. All workflows leverage the aiwebfeeds CLI for consistent execution across environments.

🎯 Overview

Our CI/CD pipeline enforces:

✅ Code Quality: Linting, formatting, and type checking
🧪 Testing: Unit, integration, and E2E tests with coverage
🔒 Security: CodeQL analysis and dependency scanning
📊 Feed Validation: RSS/Atom feed schema compliance
🤖 Automation: Auto-fixing, labeling, and release management

📋 Workflow Categories

Quality Enforcement

`quality-enforcement.yml` - Comprehensive Quality Gate

Triggers: Pull requests to main or develop

What it does:

Python Quality Checks
- Ruff linting (uv run ruff check)
- Ruff formatting (uv run ruff format --check)
- MyPy type checking (uv run mypy)
- Import sorting validation
Web Quality Checks
- ESLint (pnpm lint)
- TypeScript type checking (pnpm tsc --noEmit)
- Link validation (pnpm lint:links)
- Build verification (pnpm build)
CLI Integration
- Feed validation (uv run ai-web-feeds validate all)
- Analytics generation (uv run ai-web-feeds analytics summary)
- Export verification (uv run ai-web-feeds export all --output-dir data)
Test Suite
- Unit tests (≥90% coverage required)
- Integration tests
- E2E tests
- Coverage reporting to Codecov

Required Status: ✅ Must pass for merge

# Example: Running quality checks locally
uv run ruff check .
uv run ruff format --check .
uv run mypy .
cd apps/web && pnpm lint

`python-quality.yml` - Python-Specific Quality

Triggers: Push to any branch, PRs

What it does:

Matrix testing across Python 3.11, 3.12, 3.13
Parallel linting, formatting, type checking
CLI command validation
Package build verification

Strategy: Fast feedback on Python changes

Testing & Coverage

`coverage.yml` - Comprehensive Test Coverage

Triggers: Push to main/develop, PRs

What it does:

Runs full test suite with pytest-cov
Generates HTML and XML coverage reports
Uploads to Codecov with threshold enforcement
Validates ≥90% coverage requirement
Posts coverage report as PR comment

CLI Integration:

# Run tests with CLI validation
uv run pytest --cov=ai_web_feeds --cov-report=html --cov-report=xml

# Validate feeds after tests
uv run ai-web-feeds validate all --strict

Artifacts:

coverage-report - HTML coverage report
coverage-xml - XML for Codecov

Feed Validation

`validate-all-feeds.yml` - Complete Feed Validation

Triggers:

Push to main
Daily schedule (6 AM UTC)
Manual dispatch

What it does:

# 1. Schema validation
uv run ai-web-feeds validate feeds --strict

# 2. URL reachability checks
uv run ai-web-feeds validate http

# 3. Feed parsing validation
uv run ai-web-feeds validate feeds

# 4. OPML export verification
uv run ai-web-feeds opml all --output data/feeds.opml

# 5. Analytics generation
uv run ai-web-feeds analytics export --output data/analytics.csv

Notifications: Posts summary to Slack/Discord on failures

`validate-feed-submission.yml` - PR Feed Validation

Triggers: Pull requests modifying data/feeds.yaml

What it does:

Validates only changed feeds (incremental validation)
Checks schema compliance
Tests URL accessibility
Verifies feed parsing
Ensures no duplicates
Validates topic assignments

CLI Usage:

# Validate specific feeds
uv run ai-web-feeds validate http --feed-id openai-blog

# Validate with strict schema
uv run ai-web-feeds validate feeds --file data/feeds.yaml --strict

Auto-labels: Adds feeds:valid or feeds:invalid label

`add-approved-feed.yml` - Automated Feed Addition

Triggers: Issue labeled feed:approved

What it does:

Parses feed URL from issue body
Validates feed structure
Enriches metadata with ai-web-feeds enrich
Creates PR with new feed
Auto-assigns reviewers

CLI Integration:

# Extract feed from issue
FEED_URL=$(gh issue view $ISSUE_NUMBER --json body -q .body | grep -oP 'https?://\S+')

# Validate and enrich
uv run ai-web-feeds validate http --feed-id <feed-id>
uv run ai-web-feeds enrich one <feed-id> --input data/feeds.yaml

Auto-Fixing

`auto-fix.yml` - Automated Code Fixes

Triggers:

Comment /fix on PR
Push to branches with autofix/** prefix

What it does:

Python Fixes:

uv run ruff check --fix .
uv run ruff format .

Web Fixes:
```
cd apps/web
pnpm lint --fix
```

Feed Fixes:

# Re-enrich feeds to fix metadata
uv run ai-web-feeds enrich all

# Regenerate OPML with correct structure
uv run ai-web-feeds opml categorized --output data/feeds.categorized.opml

Auto-commit: Pushes fixes back to PR branch

Safety: Only runs on PRs, never on main

PR Validation

`pr-validation.yml` - Pull Request Quality Gate

Triggers: Pull request events (opened, synchronized, reopened)

What it does:

Title Validation: Enforces conventional commits
Label Validation: Requires type labels
Size Check: Warns on large PRs (>500 lines)
Linked Issues: Verifies issue references
CLI Validation: Runs relevant CLI commands based on changes

Change Detection:

# Runs different CLI commands based on changes
if: contains(steps.changes.outputs.files, 'data/feeds.yaml')
run: uv run ai-web-feeds validate all

if: contains(steps.changes.outputs.files, 'packages/ai_web_feeds/')
run: uv run ai-web-feeds test coverage

if: contains(steps.changes.outputs.files, 'apps/web/')
run: cd apps/web && pnpm lint && pnpm build

Security

`codeql-analysis.yml` - Security Scanning

Triggers:

Push to main/develop
Weekly schedule
PRs to main

What it does:

CodeQL scanning for Python and TypeScript
Dependency vulnerability scanning
Secret scanning
SAST analysis

Languages: Python, JavaScript, TypeScript

`dependency-review.yml` - Dependency Security

Triggers: Pull requests

What it does:

Reviews new dependencies for vulnerabilities
Checks license compatibility
Validates dependency updates
Blocks PRs with high/critical vulnerabilities

Automation

`label-manager.yml` - Automatic Labeling

Triggers: Pull requests, issues

What it does:

Auto-labels based on file paths
- python - Changes to .py files
- web - Changes to apps/web/
- cli - Changes to apps/cli/
- feeds - Changes to data/feeds.yaml
- docs - Changes to .mdx files
Adds size labels (size/S, size/M, size/L, size/XL)
Detects breaking changes from commit messages

CLI Integration:

# Generate labels from feed changes
uv run ai-web-feeds analytics --changed-feeds --output labels.json

`release-drafter.yml` - Automated Release Notes

Triggers: Push to main, merged PRs

What it does:

Groups changes by type (features, fixes, docs, etc.)
Generates changelog from PR titles
Creates draft release
Suggests version bump (semver)

Template: Uses .github/release-drafter.yml template

`release.yml` - Automated Releases

Triggers:

Tag push (v*)
Manual dispatch

What it does:

Build Artifacts:

# Python package
uv build

# CLI binary
uv run pyinstaller apps/cli/ai_web_feeds/cli/__init__.py

# Web static export
cd apps/web && pnpm build && pnpm export

Publish:
- PyPI: uv publish
- GitHub Release: Attach binaries
- Docker: Build and push container
Notifications: Slack/Discord release announcement

CLI Validation:

# Verify CLI works before release
uv run ai-web-feeds --version
uv run ai-web-feeds validate all
uv run ai-web-feeds test quick

Maintenance

`dependency-updates.yml` - Automated Dependency Updates

Triggers: Weekly schedule (Monday 9 AM UTC)

What it does:

Python: uv lock --upgrade
Web: pnpm update --interactive
Creates PR with updates
Runs full test suite
Auto-merges if tests pass (patch versions only)

`stale.yml` - Stale Issue Management

Triggers: Daily schedule

What it does:

Marks issues stale after 60 days
Closes after 14 more days
Exempts pinned, security, bug labels
Posts friendly reminder comments

🔧 CLI Command Reference

All workflows use these CLI commands:

Validation

# Validate all feeds
uv run ai-web-feeds validate all

# Validate specific feeds
uv run ai-web-feeds validate http --feed-id <feed-id>

# Schema validation only
uv run ai-web-feeds validate feeds

# Check URL accessibility
uv run ai-web-feeds validate http

# Strict mode (fail on warnings)
uv run ai-web-feeds validate all --strict

Analytics

# Generate analytics
uv run ai-web-feeds analytics summary

# Output to file
uv run ai-web-feeds analytics export --output data/analytics.csv

# Specific metrics
uv run ai-web-feeds analytics summary

Export

# Export to OPML
uv run ai-web-feeds opml all --output feeds.opml

# Export to JSON
uv run ai-web-feeds export json --output feeds.json

# Export with validation
uv run ai-web-feeds export all --output-dir data

Enrichment

# Enrich all feeds
uv run ai-web-feeds enrich all

# Enrich specific feed
uv run ai-web-feeds enrich one openai-blog

# Fix schema issues
uv run ai-web-feeds enrich all

Testing

# Run test suite via CLI
uv run ai-web-feeds test

# Quick tests only
uv run ai-web-feeds test quick

# With coverage
uv run ai-web-feeds test coverage

🚀 Running Workflows Locally

Install Act (GitHub Actions locally)

brew install act

Run Specific Workflow

# Quality enforcement
act pull_request -W .github/workflows/quality-enforcement.yml

# Coverage tests
act push -W .github/workflows/coverage.yml

# Feed validation
act workflow_dispatch -W .github/workflows/validate-all-feeds.yml

Run with Secrets

# Create .secrets file
echo "CODECOV_TOKEN=your_token" > .secrets

# Run with secrets
act -s .secrets

📊 Workflow Status Badges

Add to README:

![Quality](https://github.com/wyattowalsh/ai-web-feeds/workflows/quality-enforcement/badge.svg)
![Coverage](https://github.com/wyattowalsh/ai-web-feeds/workflows/coverage/badge.svg)
![Feeds](https://github.com/wyattowalsh/ai-web-feeds/workflows/validate-all-feeds/badge.svg)

🔍 Troubleshooting

Workflow Fails on CLI Command

Problem: ai-web-feeds: command not found

Solution: Ensure workflow uses uv run:

- name: Validate feeds
  run: uv run ai-web-feeds validate all

Coverage Below Threshold

Problem: Coverage report shows less than 90%

Solution:

Check coverage report: open reports/coverage/index.html
Add missing tests
Run locally: uv run pytest --cov --cov-report=html

Feed Validation Timeout

Problem: Feed URL checks timeout

Solution: Increase timeout in workflow:

- name: Validate with longer timeout
  run: uv run ai-web-feeds validate http

CLI Commands - Complete CLI reference
Testing Guide - Testing best practices
Contributing - Contribution workflow
Feed Schema - Feed data structure

🤖 Best Practices

Always use uv run for CLI commands in workflows
Cache dependencies to speed up builds
Run workflows locally with act before pushing
Keep workflows focused - one responsibility per workflow
Use CLI for consistency - avoid duplicating logic in YAML
Fail fast - validate critical things first
Provide clear error messages in CLI output
Matrix test across Python versions
Auto-fix when possible - reduce manual work
Monitor workflow usage - optimize slow jobs

Last Updated: October 2025

GitHub Actions Workflows

On this page