Skip to content

GITHUB_ACTIONS_SETUP.md

Latest commit

 

History

History
226 lines (164 loc) · 4.5 KB

GITHUB_ACTIONS_SETUP.md

File metadata and controls

226 lines (164 loc) · 4.5 KB
Raw

GitHub Actions Setup Guide

Quick Start

1. Create PyPI Token

  1. Go to https://pypi.org/manage/account/tokens/
  2. Create new token with scope "Entire account"
  3. Copy token

2. Add Repository Secret

  1. Go to repository Settings
  2. Secrets and variables → Actions
  3. New repository secret
  4. Name: PYPI_API_TOKEN
  5. Value: Paste token from step 1

3. Create PyPI Environment

  1. Go to Settings → Environments
  2. New environment
  3. Name: pypi
  4. (Optional) Add deployment branch restrictions

4. Enable Branch Protection

  1. Go to Settings → Branches
  2. Add branch protection rule
  3. Branch name pattern: main
  4. Require status checks:
    • lint
    • test (Python 3.12)
    • build

Workflows Overview

python-ci.yml (Main CI)

  • Runs on: Push to main/develop, PRs, manual trigger
  • Jobs: Lint, Test (3.11/3.12/3.13), Security, Build
  • Time: ~5-10 minutes

python-security.yml (Security)

  • Runs on: Push, PRs, daily schedule, manual trigger
  • Jobs: CodeQL, Dependency check, Secret scan, SBOM
  • Time: ~10-15 minutes

python-release.yml (Release)

  • Runs on: Tag push (v*..), manual trigger
  • Jobs: Verify CI, Build, Publish to PyPI, Create Release
  • Time: ~5 minutes

Testing Workflows Locally

Using act (GitHub Actions locally)

# Install act
brew install act

# Run CI workflow
act push -j lint
act push -j test

# Run with specific Python version
act push -j test --matrix python-version:3.12

Manual Testing

# Test linting
ruff check src tests
ruff format --check src tests

# Test type checking
pyright src

# Test with coverage
pytest --cov=src/ai_project --cov-fail-under=80

# Test security
bandit -r src
pip-audit

Common Issues & Solutions

Issue: Tests fail on Python 3.13

Solution: Check for compatibility issues, update dependencies

Issue: Coverage below 80%

Solution: Add tests for uncovered code, check coverage report

Issue: Linting fails

Solution: Run ruff check --fix src tests to auto-fix

Issue: Type checking fails

Solution: Add type hints, check pyproject.toml Pyright config

Issue: Release fails

Solution: Verify tag format (v*..), check PyPI token

Monitoring

View Workflow Runs

# List recent runs
gh run list

# View specific run
gh run view <run-id>

# View logs
gh run view <run-id> --log

Check Status

  • GitHub UI: Actions tab
  • Status badges in README
  • Email notifications

Customization

Add Slack Notifications

Add to workflow:

- name: Notify Slack
  if: failure()
  uses: slackapi/slack-github-action@v1
  with:
    webhook-url: ${{ secrets.SLACK_WEBHOOK }}
    payload: |
      {
        "text": "Workflow failed: ${{ github.workflow }}"
      }

Add Custom Checks

Edit python-ci.yml to add:

  • Additional linters
  • Custom tests
  • Performance benchmarks
  • Documentation builds

Modify Python Versions

Edit matrix in python-ci.yml:

matrix:
  python-version: ["3.11", "3.12", "3.13"]

Release Process

Create Release

# Create tag
git tag v1.0.0

# Push tag
git push origin v1.0.0

# Or use GitHub UI
# Releases → Draft a new release

Verify Release

  1. Check Actions tab for workflow run
  2. Verify PyPI package: https://pypi.org/project/ai-project/
  3. Check GitHub Release page
  4. Verify package installation: pip install ai-project==1.0.0

Maintenance

Update Dependencies

# Update all dependencies
pip install --upgrade -e ".[dev]"

# Update specific package
pip install --upgrade ruff pyright

# Commit changes
git add pyproject.toml
git commit -m "chore: update dependencies"

Update Workflows

  • Review GitHub Actions updates
  • Update action versions
  • Test changes in branch first
  • Merge to main when verified

Security Best Practices

  1. Rotate Tokens Regularly

    • Update PyPI token every 6 months
    • Revoke old tokens

  2. Use Least Privilege

    • PyPI token: Entire account (can be scoped to project)
    • GitHub token: Auto-generated, limited scope

  3. Monitor Secrets

    • Check secret usage in logs
    • Audit access patterns
    • Rotate if compromised

  4. Review Workflows

    • Check for hardcoded secrets
    • Verify external actions
    • Review permissions

Resources