cicaddy-github 0.1.0__tar.gz

cicaddy_github-0.1.0/.claude/skills/cicaddy-action/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: cicaddy-action
+description: >
+  Use this skill when working with cicaddy-action, the GitHub Action that wraps
+  cicaddy for running AI agent tasks in GitHub Actions workflows. Covers the
+  action inputs, Docker entrypoint, plugin architecture, task definitions, and
+  local development.
+---
+
+# cicaddy-action
+
+GitHub Action that wraps [cicaddy](https://github.com/waynesun09/cicaddy)
+for running AI agent tasks in GitHub Actions workflows. The `cicaddy-github`
+plugin extends cicaddy with GitHub-specific agents, tools, and configuration.
+
+## Working Directory
+
+- **Repository root**: `cicaddy-action/` (project root)
+- **Plugin source**: `src/cicaddy_github/`
+- **Task definitions**: `tasks/`
+- **GitHub workflows**: `.github/workflows/`
+- **Docker files**: `Dockerfile`, `entrypoint.sh`
+- **Action definition**: `action.yml`
+
+## Project Structure
+
+```
+cicaddy-action/
+  action.yml                  # GitHub Action definition (inputs/outputs)
+  Dockerfile                  # Container image (python:3.12-slim + uv)
+  entrypoint.sh               # Maps GitHub Action inputs to cicaddy env vars
+  pyproject.toml              # Package config (cicaddy-github plugin)
+  tasks/
+    pr_review.yml             # DSPy task for PR code review
+    changelog_report.yml      # DSPy task for changelog generation
+  src/cicaddy_github/
+    plugin.py                 # Entry points: register_agents, get_cli_args, etc.
+    config/settings.py        # Settings class extending CoreSettings
+    github_integration/
+      agents.py               # GitHubPRAgent, GitHubTaskAgent
+      analyzer.py             # PyGithub wrapper (diff, PR data, comments)
+      detector.py             # Auto-detect agent type from GitHub env
+      tools.py                # Git operations (@tool decorated)
+    security/
+      leak_detector.py        # Secret redaction via detect-secrets
+  .github/workflows/
+    ci.yml                    # Lint, test (3.11-3.13), docker build
+    pr-review.yml             # AI code review on PRs (uses ./action)
+    changelog.yml             # Changelog report on releases
+    release.yml               # PyPI publish
+```
+
+## Key Commands
+
+```bash
+# Install with test dependencies
+uv pip install -e ".[test]"
+
+# Run tests with coverage
+pytest tests/ -q --cov=src/cicaddy_github
+
+# Run all linters (pre-commit)
+pre-commit run --all-files
+
+# Build Docker image
+docker build -t cicaddy-action:test .
+
+# Test Docker image
+docker run --rm --entrypoint cicaddy cicaddy-action:test --version
+```
+
+## GitHub Secrets
+
+AI API keys must be configured in GitHub repository settings
+(Settings > Secrets and variables > Actions). Two approaches work:
+
+**Option 1: Generic secret via `ai_api_key` input (recommended)**
+
+Set `AI_API_KEY` as a GitHub secret. The entrypoint maps it to the correct
+provider-specific env var (`GEMINI_API_KEY`, `OPENAI_API_KEY`, or
+`ANTHROPIC_API_KEY`) based on the `ai_provider` input.
+
+```yaml
+with:
+  ai_provider: gemini
+  ai_api_key: ${{ secrets.AI_API_KEY }}
+```
+
+**Option 2: Provider-specific secret via `env:`**
+
+Set the provider-specific secret directly (e.g. `GEMINI_API_KEY`) and pass
+it as an environment variable. Cicaddy reads these env vars directly.
+
+```yaml
+with:
+  ai_provider: gemini
+env:
+  GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+```
+
+| Secret | Required | Description |
+|--------|----------|-------------|
+| `AI_API_KEY` | Yes* | Generic AI provider API key (used via `ai_api_key` input) |
+| `GEMINI_API_KEY` | Yes* | Gemini API key (alternative, passed via `env:`) |
+| `OPENAI_API_KEY` | Yes* | OpenAI API key (alternative, passed via `env:`) |
+| `ANTHROPIC_API_KEY` | Yes* | Anthropic API key (alternative, passed via `env:`) |
+| `CONTEXT7_API_KEY` | No | API key for Context7 MCP server (optional) |
+
+*One of `AI_API_KEY` or the provider-specific key is required.
+
+`GITHUB_TOKEN` is provided automatically by GitHub Actions.
+
+## Action Inputs
+
+All inputs use **underscores** (not hyphens) so GitHub Actions Docker containers
+can reference them as bash variables (`INPUT_AI_PROVIDER`, `INPUT_AI_API_KEY`, etc.).
+
+| Input | Required | Description |
+|-------|----------|-------------|
+| `ai_provider` | Yes | `gemini`, `openai`, `claude` |
+| `ai_model` | Yes | Model identifier |
+| `ai_api_key` | Yes* | AI provider API key (mapped to provider-specific env var) |
+| `task_file` | No | Path to DSPy YAML task file |
+| `task_prompt` | No | Inline task prompt |
+| `post_pr_comment` | No | Post results as PR comment (default: `false`) |
+| `github_token` | No | GitHub token (default: `${{ github.token }}`) |
+| `mcp_servers_config` | No | JSON array of MCP server configs |
+| `slack_webhook_url` | No | Slack webhook URL |
+| `report_template` | No | Custom HTML report template path |
+
+*Not required if provider-specific key is set via `env:`.
+
+## Entrypoint Flow
+
+`entrypoint.sh` bridges GitHub Action inputs to cicaddy environment:
+
+1. Exports `AI_PROVIDER` and `AI_MODEL` from `INPUT_*` vars
+2. Maps `INPUT_AI_API_KEY` to provider-specific env var (`GEMINI_API_KEY`, etc.)
+3. Resolves `AI_TASK_FILE` and `REPORT_TEMPLATE` to absolute paths (required
+   because step 5 changes the working directory)
+4. Extracts `GITHUB_PR_NUMBER` from `GITHUB_REF` (`refs/pull/<N>/merge`)
+5. Creates `.cicaddy/` subdirectory and `cd`s into it (cicaddy writes reports
+   to `../` relative to cwd; this ensures `../` resolves to the writable workspace)
+6. Runs `cicaddy run`
+
+### Known Pitfalls
+
+- **Relative paths break after `cd .cicaddy/`**: Any file path input (task file,
+  report template) must be resolved to an absolute path before the `cd`. The
+  entrypoint handles this with a `_to_abs` helper. If new file-path inputs are
+  added, they must also use this helper.
+- **Secrets in workflow `run:` blocks**: Never use `${{ secrets.* }}` directly
+  in `run:` shell blocks. Pass secrets via `env:` to avoid literal interpolation
+  in logs. See `.github/workflows/pr-review.yml` for the correct pattern.
+
+## Plugin Architecture
+
+The `cicaddy-github` package registers with cicaddy via `pyproject.toml` entry points:
+
+```toml
+[project.entry-points."cicaddy.agents"]
+github = "cicaddy_github.plugin:register_agents"
+
+[project.entry-points."cicaddy.settings_loader"]
+github = "cicaddy_github.config.settings:load_settings"
+
+[project.entry-points."cicaddy.cli_args"]
+github = "cicaddy_github.plugin:get_cli_args"
+
+[project.entry-points."cicaddy.env_vars"]
+github = "cicaddy_github.plugin:get_env_vars"
+
+[project.entry-points."cicaddy.validators"]
+github = "cicaddy_github.plugin:validate"
+```
+
+### Registered Agents
+
+| Type | Class | Triggered by |
+|------|-------|--------------|
+| `github_pr` | `GitHubPRAgent` | `GITHUB_EVENT_NAME=pull_request` + `GITHUB_PR_NUMBER` |
+| `github_task` | `GitHubTaskAgent` | `GITHUB_EVENT_NAME` present but not a PR |
+
+### Settings
+
+`Settings` extends `CoreSettings` with GitHub-specific fields:
+
+- `github_token`, `github_repository`, `github_ref`, `github_event_name`
+- `github_sha`, `github_run_id`, `github_pr_number`
+- `post_pr_comment` (bool)
+
+All loaded from environment variables via `load_settings()`.
+
+## DSPy Task Files
+
+Task YAML files define analysis prompts. Inputs use `{{VAR}}` placeholders
+resolved from environment variables.
+
+```yaml
+name: pr_code_review
+type: code_review
+version: "1.0"
+
+persona: >
+  expert code reviewer
+
+tools:
+  servers:
+    - local
+  required_tools:
+    - read_file
+    - glob_files
+
+output_format: markdown
+
+context: |
+  Review the PR diff for the repository...
+```
+
+## Workflow Usage
+
+```yaml
+- uses: redhat-community-ai-tools/cicaddy-action@v0
+  with:
+    ai_provider: gemini
+    ai_model: gemini-3-flash-preview
+    ai_api_key: ${{ secrets.AI_API_KEY }}
+    task_file: tasks/pr_review.yml
+    post_pr_comment: 'true'
+    github_token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+## Running Locally
+
+Cicaddy can run locally to review PRs without GitHub Actions. Create an env
+file and use `uv run cicaddy run --env-file <file>`.
+
+### Env File Template (PR Review)
+
+```bash
+# AI Provider
+AI_PROVIDER=gemini
+AI_MODEL=gemini-3-flash-preview
+GEMINI_API_KEY=<key>
+
+# GitHub Configuration
+GITHUB_TOKEN=<token>            # gh auth token
+GITHUB_REPOSITORY=owner/repo
+GITHUB_EVENT_NAME=pull_request
+GITHUB_PR_NUMBER=42
+
+# Agent Settings
+POST_PR_COMMENT=true
+ENABLE_LOCAL_TOOLS=true
+LOCAL_TOOLS_WORKING_DIR=.
+
+# Optional: MCP servers
+MCP_SERVERS_CONFIG=[{"name": "context7", "protocol": "http", "endpoint": "https://mcp.context7.com/mcp", "headers": {"CONTEXT7_API_KEY": "<key>"}}]
+
+LOG_LEVEL=INFO
+```
+
+### Key Commands
+
+```bash
+# Install plugin in editable mode (uses live code)
+uv pip install -e ".[test]"
+
+# Run a PR review
+uv run cicaddy run --env-file .env.my-review
+
+# Validate configuration
+uv run cicaddy validate --env-file .env.my-review
+```
+
+### Agent Type Detection
+
+The agent type is auto-detected by `_detect_github_agent_type` in
+`src/cicaddy_github/github_integration/detector.py` (registered at priority 40):
+- `GITHUB_EVENT_NAME=pull_request` → `github_pr`
+- `GITHUB_PR_NUMBER` set (fallback) → `github_pr`
+- Otherwise → falls through to core detectors
+
+### Additional Env Vars
+
+- `AI_TASK_FILE`: Path to DSPy YAML task file for custom workflows
+- `GIT_DIFF_CONTEXT_LINES`: Number of context lines in diffs (default: 10)
+
+### MCP Server Config Format
+
+JSON array. Each server object has:
+- `name` (string): Server identifier
+- `protocol` (string): `http`, `sse`, `stdio`, or `websocket`
+- `endpoint` (string): Server URL
+- `headers` (object, optional): HTTP headers (e.g. API keys)
+
+### Notes
+
+- **Never commit env files with secrets.** Use `.env.*` pattern (already in `.gitignore`)
+- `POST_PR_COMMENT=true` requires a token with write access to pull requests
+  (`repo` scope includes this; for fine-grained tokens, enable "Pull requests: Write")
+- The `github_pr` agent updates its PR comment in-place on re-runs
+- Use `gh auth token` to generate a GitHub token quickly
+
+## Code Style
+
+- Python 3.11+ with type hints
+- Ruff for linting and formatting (line-length 100)
+- Google-style docstrings
+- Async methods for I/O operations
+- `@tool` decorator for local tool definitions
+- pytest with pytest-asyncio for testing

cicaddy_github-0.1.0/.github/dependabot.yml

@@ -0,0 +1,24 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"

cicaddy_github-0.1.0/.github/workflows/changelog.yml

@@ -0,0 +1,66 @@
+name: Generate Changelog Report
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      from_tag:
+        description: 'Start tag'
+        required: false
+      to_tag:
+        description: 'End tag (default: latest)'
+        required: false
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Generate Report
+        uses: ./
+        id: report
+        with:
+          ai_provider: gemini
+          ai_model: gemini-2.5-flash
+          ai_api_key: ${{ secrets.AI_API_KEY }}
+          task_file: tasks/changelog_report.yml
+        env:
+          FROM_TAG: ${{ inputs.from_tag || '' }}
+          TO_TAG: ${{ inputs.to_tag || github.event.release.tag_name || 'HEAD' }}
+          REPORT_TITLE: "Cicaddy Action — Release Update"
+
+      - name: Upload report artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: changelog-report
+          path: ${{ steps.report.outputs.report_html }}
+
+      - name: Prepare Pages
+        run: |
+          mkdir -p _site
+          cp "${{ steps.report.outputs.report_html }}" _site/index.html
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: _site
+
+  deploy:
+    needs: generate
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

cicaddy_github-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - uses: astral-sh/setup-uv@v7
+      - name: Install dependencies
+        run: |
+          uv pip install --system pre-commit
+          uv pip install --system -e ".[test]"
+      - name: Run pre-commit (skip ty)
+        run: SKIP=ty pre-commit run --all-files
+      - name: Run ty check
+        run: uvx ty check --python "$(python3 -c 'import sys; print(sys.prefix)')"
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v7
+      - name: Install dependencies
+        run: uv pip install --system -e ".[test]"
+      - name: Run tests with coverage
+        run: pytest tests/ -q --cov=src/cicaddy_github --cov-report=xml
+      - name: Upload coverage
+        if: matrix.python-version == '3.13'
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-report
+          path: coverage.xml
+
+  docker-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Build Docker image
+        run: docker build -t cicaddy-action:test .
+      - name: Test Docker image runs
+        run: docker run --rm --entrypoint cicaddy cicaddy-action:test --version

cicaddy_github-0.1.0/.github/workflows/pr-review.yml

@@ -0,0 +1,45 @@
+name: AI PR Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  review:
+    if: ${{ github.actor != 'dependabot[bot]' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Build MCP config
+        id: mcp
+        env:
+          CONTEXT7_KEY: ${{ secrets.CONTEXT7_API_KEY }}
+        run: |
+          # Context7 is optional — only include if secret is configured
+          if [ -n "${CONTEXT7_KEY}" ]; then
+            echo "config=[{\"name\":\"Context7\",\"protocol\":\"http\",\"endpoint\":\"https://mcp.context7.com/mcp\",\"headers\":{\"CONTEXT7_API_KEY\":\"${CONTEXT7_KEY}\"},\"timeout\":300,\"idle_timeout\":60}]" >> "$GITHUB_OUTPUT"
+          else
+            echo 'config=[]' >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: AI Code Review
+        uses: ./
+        id: review
+        with:
+          ai_provider: gemini
+          ai_model: gemini-3-flash-preview
+          ai_api_key: ${{ secrets.AI_API_KEY }}
+          task_file: tasks/pr_review.yml
+          post_pr_comment: 'true'
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          mcp_servers_config: ${{ steps.mcp.outputs.config }}
+        env:
+          ANALYSIS_FOCUS: "general"
+          GIT_DIFF_CONTEXT_LINES: "15"

cicaddy_github-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,101 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+  packages: write
+  id-token: write
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Build release distributions
+        run: uv build
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: release-dists
+          path: dist/
+
+  docker-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  github-release:
+    needs: [release-build, docker-publish]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+
+  pypi-publish:
+    needs: release-build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cicaddy-github
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: release-dists
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  update-major-tag:
+    needs: github-release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Update major version tag
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          MAJOR="${TAG%%.*}"
+          git tag -f "$MAJOR" "$TAG"
+          git push origin "$MAJOR" --force

cicaddy_github-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.*
+.env.local
+
+# Claude Code local settings (contains developer-specific paths)
+.claude/settings.local.json
+
+# UV
+uv.lock

cicaddy_github-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,56 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-yaml
+        args: ['--unsafe']
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: detect-private-key
+      - id: check-added-large-files
+        args: ['--maxkb=1000']
+      - id: check-merge-conflict
+      - id: check-json
+      - id: check-toml
+      - id: debug-statements
+      - id: mixed-line-ending
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty check
+        entry: uvx ty check
+        language: system
+        types: [python]
+        pass_filenames: false
+        exclude: ^(tests/)
+
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.9.3
+    hooks:
+      - id: bandit
+        args: ['-c', 'pyproject.toml', '-r', 'src/']
+        additional_dependencies: ['bandit[toml]']
+        pass_filenames: false
+
+  - repo: https://github.com/zricethezav/gitleaks
+    rev: v8.30.0
+    hooks:
+      - id: gitleaks
+
+  - repo: https://github.com/hadolint/hadolint
+    rev: v2.13.1-beta
+    hooks:
+      - id: hadolint-docker
+
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.7
+    hooks:
+      - id: actionlint