This guide helps you solve common issues when using GitHub Actions Simple for data science projects.
Is your workflow failing? Follow this decision tree:
Workflow Failed?
├── Setup Phase Failed? → See "Python & UV Issues"
├── Tests Failed? → See "Testing Issues"
├── Quality Check Failed? → See "Code Quality Issues"
├── Notebook Test Failed? → See "Notebook Issues"
└── Unknown Error? → See "General Debugging"
```text
---
## Python & UV Issues
### Issue: "UV not found" or "command not found: uv"
**Symptoms:**
```text
/bin/bash: line 1: uv: command not found
Error: Process completed with exit code 127
```text
**Solutions:**
**1. Check UV Installation:**
```yaml
- name: Debug UV Installation
run: |
echo "Checking UV installation..."
which uv || echo "UV not found in PATH"
echo "PATH: $PATH"
ls -la $HOME/.cargo/bin/ || echo "Cargo bin directory not found"
```text
**2. Manual UV Installation:**
```yaml
- name: Install UV Manually
run: |
curl -LsSf https://astral.sh/uv/install.sh | sh
echo "$HOME/.cargo/bin" >> $GITHUB_PATH
source $HOME/.cargo/env
```text
**3. Platform-Specific Issues:**
```yaml
# For Windows runners
- name: Install UV (Windows)
run: |
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
echo "$env:USERPROFILE\.cargo\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
```text
### Issue: "Python version not found"
**Symptoms:**
```text
error: No interpreter found for Python 3.11 in virtual environment
```text
**Solutions:**
**1. Use Available Python Version:**
```yaml
- uses: ./actions/setup-python-uv
with:
python-version: '3.x' # Use latest available
```text
**2. Explicit Python Setup:**
```yaml
- uses: actions/setup-python@v4
with:
python-version: '3.11'
- uses: ./actions/setup-python-uv
with:
python-version: '3.11'
```text
### Issue: "Permission denied" during installation
**Symptoms:**
```text
Permission denied (publickey)
error: failed to download from `https://pypi.org/simple/`
```text
**Solutions:**
**1. Check Network Access:**
```yaml
- name: Test Network
run: |
curl -I https://pypi.org/simple/
ping -c 3 pypi.org
```text
**2. Use Alternative Index:**
```yaml
- uses: ./actions/setup-python-uv
with:
index-url: 'https://pypi.python.org/simple/'
```text
---
## Testing Issues
### Issue: "No tests ran" or "collection failed"
**Symptoms:**
```text
collected 0 items
ERROR: not found: */tests/
```text
**Solutions:**
**1. Check Test Discovery:**
```yaml
- name: Debug Test Discovery
run: |
find . -name "test_*.py" -o -name "*_test.py"
find . -name "tests" -type d
ls -la tests/ || echo "No tests directory"
```text
**2. Specify Test Path:**
```yaml
- uses: ./actions/pytest-uv
with:
test-path: 'src/tests/' # Adjust to your structure
```text
**3. Different Test Patterns:**
```yaml
- uses: ./actions/pytest-uv
with:
pytest-args: '--collect-only -q' # See what would be collected
```text
### Issue: Tests pass locally but fail in CI
**Common Causes & Solutions:**
**1. Missing Dependencies:**
```yaml
# Add debug step
- name: List Installed Packages
run: uv pip list
# Check your requirements.txt includes all test dependencies
# Add missing packages:
pytest>=7.0.0
pytest-cov>=4.0.0
```text
**2. Path Issues:**
```python
# In your tests, use relative imports
from src.mymodule import MyClass # Might fail in CI
from mymodule import MyClass # Better
# Or fix Python path in conftest.py
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
```text
**3. Environment Variables:**
```yaml
- uses: ./actions/pytest-uv
env:
DATABASE_URL: sqlite:///:memory:
API_KEY: test-key-123
```text
### Issue: "Coverage threshold not met"
**Symptoms:**
```text
FAIL Required test coverage of 90% not reached. Total coverage: 75.23%
```text
**Solutions:**
**1. Lower Threshold Temporarily:**
```yaml
- uses: ./actions/pytest-uv
with:
coverage-threshold: 70 # Lower until you add more tests
```text
**2. Exclude Files from Coverage:**
```toml
# pyproject.toml
[tool.coverage.run]
omit = [
"*/tests/*",
"*/venv/*",
"setup.py",
"conftest.py"
]
```text
**3. Focus Coverage on Important Code:**
```toml
[tool.coverage.run]
source = ["src/"] # Only measure coverage in src/
```text
---
## Code Quality Issues
### Issue: "Ruff violations found"
**Symptoms:**
```text
error: Found 23 errors (12 fixed, 11 remaining)
src/data_processing.py:45:1: E302 expected 2 blank lines, found 1
```text
**Solutions:**
**1. Auto-fix Issues:**
```yaml
- uses: ./actions/code-quality-uv
with:
fix-violations: true # Auto-fix what's possible
```text
**2. Ignore Specific Rules:**
```toml
# pyproject.toml
[tool.ruff]
ignore = [
"E501", # Line too long
"F401", # Unused import
]
```text
**3. Gradual Adoption:**
```yaml
- uses: ./actions/code-quality-uv
with:
fail-on-violations: false # Warning only
```text
### Issue: "MyPy type checking errors"
**Symptoms:**
```text
error: Cannot determine type of 'data'
error: Argument 1 to "process" has incompatible type "str"; expected "int"
```text
**Solutions:**
**1. Disable Strict Mode:**
```toml
# pyproject.toml
[tool.mypy]
strict = false
check_untyped_defs = false
```text
**2. Add Type Annotations Gradually:**
```python
# Before
def process_data(data):
return data * 2
# After
def process_data(data: int) -> int:
return data * 2
```text
**3. Skip Files Temporarily:**
```toml
[tool.mypy]
exclude = [
"legacy_code/",
"experimental/",
]
```text
---
## Notebook Issues
### Issue: "Notebook execution failed"
**Symptoms:**
```text
CellExecutionError: An error occurred while executing the following cell:
KeyError: 'missing_column'
```text
**Solutions:**
**1. Check Data Dependencies:**
```yaml
- name: Setup Test Data
run: |
mkdir -p data/
echo "sample,data" > data/test.csv
- uses: ./actions/notebook-test-uv
```text
**2. Skip Problematic Cells:**
```python
# In notebook cell, add tag to skip
# Cell metadata: {"tags": ["skip-ci"]}
```text
**3. Increase Timeout:**
```yaml
- uses: ./actions/notebook-test-uv
with:
timeout: 600 # 10 minutes instead of default 60
```text
### Issue: "Kernel not found"
**Symptoms:**
```text
No such kernel named python3
```text
**Solutions:**
**1. Install Jupyter Kernel:**
```yaml
- name: Setup Jupyter Kernel
run: |
uv pip install ipykernel
uv run python -m ipykernel install --user --name python3
```text
**2. Use Papermill with Specific Kernel:**
```yaml
- uses: ./actions/notebook-test-uv
with:
kernel-name: 'python3'
```text
### Issue: "Notebooks have outputs"
**Symptoms:**
```text
Notebook contains outputs. Please clear outputs before committing.
```text
**Solutions:**
**1. Auto-clear Outputs:**
```yaml
- uses: ./actions/notebook-test-uv
with:
clear-outputs: true
```text
**2. Git Hook to Clear Outputs:**
```bash
# .git/hooks/pre-commit
# !/bin/sh
jupyter nbconvert --clear-output --inplace notebooks/*.ipynb
```text
---
## General Debugging
### Enable Debug Mode
**1. GitHub Actions Debug:**
```yaml
- uses: ./actions/setup-python-uv
env:
ACTIONS_STEP_DEBUG: true
ACTIONS_RUNNER_DEBUG: true
```text
**2. Verbose Output:**
```yaml
- uses: ./actions/pytest-uv
with:
pytest-args: '-v --tb=long'
```text
### Common Workflow Issues
**1. Action Not Found:**
```text
Error: Can't find 'action.yml', 'action.yaml' or 'Dockerfile'
```text
**Solution:** Check action path and ensure actions folder is in repository root:
```text
your-repo/
├── actions/ # Must be here
│ └── setup-python-uv/
├── .github/
│ └── workflows/
```text
**2. Permissions Issues:**
```text
Error: Resource not accessible by integration
```text
**Solution:** Check repository permissions:
```yaml
jobs:
test:
permissions:
contents: read
pull-requests: write # For coverage comments
```text
**3. Runner Out of Space:**
```text
Error: No space left on device
```text
**Solution:** Clean up space:
```yaml
- name: Free Disk Space
run: |
df -h
sudo rm -rf /usr/share/dotnet
sudo rm -rf /opt/ghc
sudo rm -rf /usr/local/share/boost
df -h
```text
---
## Performance Issues
### Slow Builds
**1. Enable Caching:**
```yaml
- uses: ./actions/setup-python-uv
with:
cache: true # Enable dependency caching
```text
**2. Parallel Testing:**
```yaml
- uses: ./actions/pytest-uv
with:
parallel: true # Use all available CPU cores
```text
**3. Reduce Test Scope:**
```yaml
# Only run tests on changed files
- uses: ./actions/pytest-uv
with:
pytest-args: '--lf' # Last failed only
```text
### Memory Issues
**1. Monitor Memory Usage:**
```yaml
- name: Check Memory
run: |
free -h
ps aux --sort=-%mem | head -10
```text
**2. Reduce Parallel Workers:**
```yaml
- uses: ./actions/pytest-uv
with:
pytest-args: '-n 2' # Limit to 2 workers
```text
---
## Verification Checklist
Before asking for help, verify:
- [ ] **Repository Structure**: Actions folder in repository root
- [ ] **File Permissions**: All action files are readable
- [ ] **Dependencies**: requirements.txt includes all needed packages
- [ ] **Python Version**: Compatible with your project
- [ ] **Test Discovery**: Tests are in expected locations
- [ ] **Network Access**: Can reach PyPI and other required services
## Getting Additional Help
### 1. Check Action Logs
- Go to GitHub → Actions tab → Click failed workflow
- Expand each step to see detailed logs
- Look for the first error (later errors often cascade)
### 2. Compare with Working Examples
- Check the `templates/` folder for working examples
- Compare your workflow with `basic-data-science.yml`
### 3. Community Support
- Create an issue in this repository
- Include:
- Your workflow file
- Error messages (full logs)
- Repository structure
- Python version and dependencies
### 4. Quick Fixes Repository
For the most common issues, we maintain example fixes:
```bash
# Clone the examples
git clone https://github.com/your-org/github-actions-simple-examples
cd github-actions-simple-examples
```text
---
## Prevention Tips
### 1. Start Simple
```yaml
# Begin with minimal workflow
- uses: ./actions/setup-python-uv
- uses: ./actions/pytest-uv
# Add complexity gradually
```text
### 2. Test Locally First
```bash
# Test UV installation locally
curl -LsSf https://astral.sh/uv/install.sh | sh
uv pip install -r requirements.txt
uv run pytest
```text
### 3. Use Matrix Testing
```yaml
strategy:
matrix:
python-version: ['3.9', '3.10', '3.11']
os: [ubuntu-latest, windows-latest]
```text
### 4. Monitor Dependencies
- Pin versions in production: `pandas==2.1.3`
- Use dependabot for updates
- Test with latest dependencies in separate workflow
---
**Pro Tip:** Most issues are caused by missing dependencies or incorrect file paths. Start by checking these first!
**Quick Links:**
- [GETTING_STARTED.md](GETTING_STARTED.md) - Step-by-step setup
- [USAGE.md](USAGE.md) - Configuration reference
- [TECHNICAL_ARCHITECTURE.md](TECHNICAL_ARCHITECTURE.md) - Advanced documentation