Installation Guide¶

System Requirements¶

Git: 2.30+
GitHub Account: With repository admin access
GitHub CLI: gh 2.0+
Python: 3.11+ (if using Python workflows)

Step 1: Clone the Repository¶

# Clone this template
git clone https://github.com/your-org/project-llm-management.git
cd project-llm-management

# Or fork and clone your fork
git clone https://github.com/YOUR_USERNAME/project-llm-management.git

Step 2: Install Dependencies (Optional)¶

If you want to run workflows locally for testing:

# Python dependencies
pip install -r requirements.txt

# Development tools (for local testing)
pip install pytest black pylint mypy mkdocs mkdocs-material

Step 3: Configure GitHub Secrets¶

Navigate to your repository settings:

Settings → Secrets and variables → Actions

Add the following secrets:

Required Secrets¶

`GITHUB_TOKEN`¶

GitHub automatically provides this, but you can also create a Personal Access Token:

gh auth login
# Select: GitHub.com
# Select: HTTPS
# Authenticate with browser

`GEMINI_API_KEY` (for Code Review and AI workflows)¶

Get your API key from aistudio.google.com
Add it to your repo secrets:

gh secret set GEMINI_API_KEY --body "AIza..."

Optional Secrets (per-workflow keys)¶

`GEMINI_REVIEW_API_KEY` (dedicated key for code review)¶

gh secret set GEMINI_REVIEW_API_KEY --body "AIza..."

`GEMINI_PLAN_API_KEY` (dedicated key for planning)¶

gh secret set GEMINI_PLAN_API_KEY --body "AIza..."

`GEMINI_SPEC_API_KEY` (dedicated key for specification)¶

gh secret set GEMINI_SPEC_API_KEY --body "AIza..."

Step 4: Enable GitHub Projects v2¶

Go to your repository
Click the Projects tab
Click New project
Select Table or Board view
Name it: Project Board
Create the project

Step 5: Configure Project Fields¶

Custom Fields to Create¶

In the project settings, add these fields:

Field Name	Type	Values
Priority	Single select	Low, Medium, High
Effort	Single select	1, 2, 3, 5, 8
Status	Single select	Backlog, In Progress, In QA, Done
Owner	People	Auto (from assignee)
Sprint	Text	v1.0, v2.0, etc.
Environment	Single select	dev, preprod, prod

Create Views¶

1. Backlog (Table)¶

Columns: Title, Priority, Effort, Owner, Status
Filter: Status != "Done"
Sort: Created date (oldest first)

2. Priority Board (Kanban)¶

Group by: Status
Filter: Priority = High OR Medium
Sort: Priority (highest first)

3. Team Items (Table)¶

Columns: Title, Owner, Sprint, Status, Due Date
Filter: Owner = me (for personal view)

Step 6: Configure Workflows¶

Most workflows are pre-configured, but verify they're enabled:

Settings → Actions → General

Ensure: - ✅ Actions workflows are enabled - ✅ Read/write permissions for Actions

Step 7: Test the Setup¶

Create a test issue¶

gh issue create \
  --title "Test: Setup verification" \
  --body "Testing the workflow setup" \
  --label "auto-branch"

This should automatically: 1. Create a branch: feat/1-test-setup-verification 2. Post a comment with checkout instructions 3. Trigger the CI workflow

Verify workflows ran¶

gh run list --workflow ci-tests.yml
gh run list --workflow create-branch.yml

Step 8: Configure MkDocs (Documentation)¶

# Install MkDocs
pip install mkdocs mkdocs-material

# Build docs locally
mkdocs build

# Serve locally
mkdocs serve
# Visit http://localhost:8000

Deploy to GitHub Pages¶

The workflow .github/workflows/deploy-docs.yml automatically deploys when you push to docs/:

Go to Settings → Pages
Set source to Deploy from a branch
Select gh-pages branch
Save

Your docs will be available at: https://your-username.github.io/project-llm-management

Step 9: Create Development Environment¶

Python Virtual Environment¶

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Install Pre-commit Hooks (Optional)¶

pip install pre-commit
pre-commit install

Step 10: Verify Installation¶

Run this checklist:

[ ] Repository cloned/forked locally
[ ] GitHub secrets configured
[ ] GitHub Projects v2 created
[ ] Workflows enabled
[ ] Test issue created and branch auto-created
[ ] MkDocs documentation built
[ ] Local development environment set up

Troubleshooting¶

Issue: Workflows not running¶

Solution: Check Settings → Actions → General → ensure workflows are enabled

Issue: Code Review Agent not working¶

Solution: Verify GEMINI_API_KEY is set correctly (no extra spaces)

Issue: Branch not created¶

Solution: Ensure auto-branch label is added to the issue

Issue: Python tests fail¶

Solution: Install all dev dependencies: pip install -r requirements.txt

Next Steps¶

✅ Quick Start Guide - Run your first workflow
📚 Architecture Overview - Understand the system
📝 Contributing Guide - Start contributing

Need help? Check the FAQ or Troubleshooting Guide