GitHub Actions Workflows¶

📋 Overview¶

Five workflows manage the complete project lifecycle:

Workflow	Trigger	Purpose	Duration
create-branch.yml	Issue labeled	Auto-create feature branch	<10s
ci-tests.yml	Push/PR	Run tests & lint	2-5 min
code-review-agent.yml	PR opened	AI code review	30-60s
update-project.yml	PR/Issue events	Sync project board	<5s
deploy-docs.yml	Docs changed	Build & deploy MkDocs	1-2 min

1️⃣ create-branch.yml¶

Purpose¶

Automatically creates a feature branch when auto-branch label is added to an issue.

Trigger¶

on:
  issues:
    types: [labeled]

Conditions¶

Label name == auto-branch
Repository has write permissions

Process¶

Issue labeled with "auto-branch"
         ↓
Extract issue #123 and title
         ↓
Slugify title: "Add auth" → "add-auth"
         ↓
Create branch: feat/123-add-auth
         ↓
Push to origin
         ↓
Comment on issue with instructions

Outputs¶

Branch created on origin
Comment posted with checkout instructions
No changes to main branch

Example¶

Issue: #42 "Implement payment system"
↓
Branch created: feat/42-implement-payment-system
↓
Comment:
✅ Branch auto-created: `feat/42-implement-payment-system`

Next steps:
1. git checkout feat/42-implement-payment-system
2. Make your changes
3. Push and create a Pull Request

Customization¶

Modify BRANCH_NAME pattern in the workflow:

# Current
BRANCH_NAME="feat/${ISSUE_NUMBER}-${SLUGIFIED}"

# Alternative
BRANCH_NAME="fix/${ISSUE_NUMBER}-${SLUGIFIED}"  # For bugs

2️⃣ ci-tests.yml¶

Purpose¶

Run comprehensive code quality checks: formatting, linting, type checking, and tests.

Triggers¶

on:
  push:
    branches: [main, develop, staging]
  pull_request:
    branches: [main, develop]

Matrix Testing¶

matrix:
  python-version: ["3.11"]

Extend to test multiple Python versions:

matrix:
  python-version: ["3.9", "3.10", "3.11", "3.12"]

Pipeline Steps¶

1. Checkout Code¶

- uses: actions/checkout@v4

2. Setup Python¶

- uses: actions/setup-python@v4
  with:
    python-version: ${{ matrix.python-version }}

3. Cache Dependencies¶

- uses: actions/cache@v3
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}

4. Format Check (Black)¶

black --check --line-length 100 src/ tests/

- Verifies code formatting - Non-blocking (continue-on-error) - Suggests fixes if fails

5. Lint (Pylint)¶

pylint src/ --disable=C0111,W0212 --fail-under=7.0

- Checks code quality - Minimum score: 7.0/10 - Non-blocking

6. Type Check (Mypy)¶

mypy src/ --ignore-missing-imports

- Static type validation - Catches type errors early - Non-blocking

7. Run Tests¶

pytest tests/ \
  --cov=src/ \
  --cov-report=xml \
  --cov-report=html \
  --junitxml=test-results.xml

- Executes all unit tests - Generates coverage reports - XML output for CI integration

8. Report Results¶

# Comment on PR with results
gh issue comment {PR} --body "..."

Example comment:

## ✅ Tests Passed

- Tests: 127/127 passed ✅
- Coverage: 85%
- Lint: OK (score: 8.5)
- Build: ✅

---
*Generated by GitHub Actions*

Build Job (Optional)¶

If applicable, builds package distribution:

python -m build

Failure Handling¶

❌ Tests fail → Status: FAILURE
⚠️ Lint warns → Status: SUCCESS (non-blocking)
🔴 Type errors → Status: SUCCESS (non-blocking)

Note: Only tests are blocking by default.

Configuration Examples¶

Increase Timeout¶

timeout-minutes: 30

Test Specific Files¶

pytest tests/test_auth.py -v

Generate HTML Coverage Report¶

Already done, accessible via: - Actions artifact → htmlcov/ - Or download locally

3️⃣ code-review-agent.yml¶

Purpose¶

Use Gemini AI to automatically review pull requests and provide constructive feedback.

Trigger¶

on:
  pull_request:
    types: [opened, synchronize, reopened]

Requirements¶

GEMINI_API_KEY secret configured (or GEMINI_REVIEW_API_KEY)
PR should be < 10000 lines (limit)
Python with google-generativeai library installed

Process¶

PR opened/updated
     ↓
Get PR diff (via gh cli)
     ↓
Prepare prompt with diff + PR description
     ↓
Call Gemini API with prompt
     ↓
Parse response (structured markdown)
     ↓
Post as PR comment
     ↓
Update project status → "In QA"

Prompt Structure¶

Review this GitHub PR code changes. Provide constructive feedback:

**PR Title**: {title}
**PR Description**: {description}

**Code Changes**:
```diff
{diff}

Provide review with: 1. ✅ Strengths 2. ⚠️ Suggestions 3. 🔴 Critical Issues

### Gemini Configuration
```python
import google.generativeai as genai
genai.configure(api_key=os.getenv('GEMINI_API_KEY'))
model = genai.GenerativeModel('gemini-2.0-flash')
response = model.generate_content(prompt)

Example Output¶

## 🤖 Automated Code Review by Gemini AI

### ✅ Strengths
- Good separation of concerns
- Proper error handling
- Clear variable names
- Well-structured functions

### ⚠️ Suggestions
- Consider adding docstrings to public functions
- Use f-strings instead of .format()
- Extract magic number 100 to named constant
- Add more test cases for edge cases

### 🔴 Critical Issues
- **Security**: Line 45 - SQL injection risk, use parameterized queries
- **Performance**: Lines 30-35 - N+1 query problem in loop

---
*This is an informational review - approval is not required for merge*

Customization¶

Change Model¶

model = genai.GenerativeModel('gemini-1.5-pro')  # Other Gemini models

Increase/Decrease Detail¶

max_tokens=2048,  # More detailed review
max_tokens=512,   # Brief review

Custom Instructions¶

Modify the prompt to focus on specific areas:

prompt = f"""Review focusing on:
1. Security vulnerabilities
2. Performance optimizations
3. Code style consistency

{original_prompt}
"""

Fallback Behavior¶

If GEMINI_API_KEY not set:

⚠️ Code review workflow encountered an error

Add GEMINI_API_KEY to GitHub Secrets to enable full AI-powered review.

4️⃣ update-project.yml¶

Purpose¶

Synchronize GitHub Projects v2 board with issue and PR updates.

Triggers¶

on:
  push:
    branches: [main, develop, staging]
  pull_request:
    types: [opened, synchronize, closed]
  issues:
    types: [opened, closed, labeled, unlabeled]

Process¶

On PR Open¶

PR created
     ↓
Extract issue number from "Closes #123" in PR body
     ↓
Update project item status → "In QA"
     ↓
Log the update

On PR Close (Merged)¶

PR merged to main
     ↓
Find linked issue
     ↓
Update status → "Done"
     ↓
Close issue if applicable

On Push¶

Commit pushed to branch
     ↓
Update project item timestamps
     ↓
Refresh board view

On Issue Event¶

Issue created/updated/labeled
     ↓
Sync with project board
     ↓
Update relevant fields

Current Limitations¶

Basic logging and status tracking
Full GraphQL integration coming soon

Future Enhancement¶

# Planned GraphQL mutation
mutation UpdateProjectStatus {
  updateProjectV2ItemFieldValue(input: {
    projectId: "ABC123"
    itemId: "DEF456"
    fieldId: "status"
    value: "Done"
  }) {
    projectV2Item { id }
  }
}

5️⃣ deploy-docs.yml¶

Purpose¶

Automatically build and deploy MkDocs documentation to GitHub Pages.

Trigger¶

on:
  push:
    branches: [main, develop]
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - '.github/workflows/deploy-docs.yml'
  workflow_dispatch:  # Manual trigger

Process¶

Changes pushed to docs/
     ↓
Workflow triggered
     ↓
Install MkDocs + Material theme
     ↓
Build static site (mkdocs build)
     ↓
Deploy to gh-pages branch
     ↓
GitHub Pages updated
     ↓
Site available at https://dyvan.github.io/github-project-llm-management

Configuration¶

- uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./site

GitHub Pages Setup¶

Go to Settings → Pages
Source: Deploy from a branch
Branch: gh-pages
Folder: / (root)
Click Save

Your docs will be live at:

https://dyvan.github.io/github-project-llm-management

Custom Domain (Optional)¶

Add to GitHub Pages settings:

your-domain.com

Then update mkdocs.yml:

site_url: https://your-domain.com

🔧 Workflow Management¶

Enable/Disable Workflows¶

Go to Actions tab
Click workflow name
Click ⋯ menu → Disable/Enable

View Workflow Runs¶

Actions → Workflow name → Click run to see details

Debug Failed Workflows¶

Click the failed run
Click the failed job
Expand steps to see logs
Look for red text/error messages

Run Workflow Manually¶

on:
  workflow_dispatch:  # Allows manual trigger

Then: 1. Go to Actions → Workflow name 2. Click Run workflow 3. Select branch and click Run

Secrets for Workflows¶

Add/update in Settings → Secrets and variables → Actions: - GEMINI_API_KEY : Google Gemini API key (required for AI features) - GEMINI_REVIEW_API_KEY : Dedicated key for code review (optional, falls back to GEMINI_API_KEY) - GEMINI_PLAN_API_KEY : Dedicated key for planning (optional, falls back to GEMINI_API_KEY) - GEMINI_SPEC_API_KEY : Dedicated key for specification (optional, falls back to GEMINI_API_KEY)

Access in workflows:

env:
  GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

📊 Workflow Metrics¶

Execution Times¶

Branch Creator: ~10 seconds
CI Tests: 2-5 minutes
Code Review: 30-60 seconds
Update Project: <5 seconds
Deploy Docs: 1-2 minutes

Cost (GitHub Actions)¶

Free tier: 2,000 minutes/month (public repos unlimited)
Typical project: ~500 minutes/month

API Costs¶

Gemini code review: ~$0.01-0.05 per review
Typical monthly: $10-30 for active project

🆘 Troubleshooting¶

Issue	Cause	Solution
Workflow doesn't run	Not enabled	Enable in Actions tab
API key error	Secret not found	Add to GitHub Secrets
Tests timeout	Too slow	Optimize test suite
PR not merging	Checks failed	Check workflow logs
Docs not deploying	Wrong branch	Ensure gh-pages exists