From 248dd4b5c847ab038b7b150a1b5846e3d8170d70 Mon Sep 17 00:00:00 2001 From: pikann Date: Wed, 13 May 2026 18:37:47 +0700 Subject: [PATCH 1/2] feat: add GitHub Actions workflows for backend, frontend, and MCP CI/CD processes --- .github/workflows/backend-pr-ci.yml | 101 +++++++++++++++++++++++++++ .github/workflows/frontend-pr-ci.yml | 53 ++++++++++++++ .github/workflows/mcp-pr-ci.yml | 53 ++++++++++++++ .github/workflows/release.yml | 93 ++++++++++++++++++++++++ 4 files changed, 300 insertions(+) create mode 100644 .github/workflows/backend-pr-ci.yml create mode 100644 .github/workflows/frontend-pr-ci.yml create mode 100644 .github/workflows/mcp-pr-ci.yml create mode 100644 .github/workflows/release.yml diff --git a/.github/workflows/backend-pr-ci.yml b/.github/workflows/backend-pr-ci.yml new file mode 100644 index 0000000..b0924b6 --- /dev/null +++ b/.github/workflows/backend-pr-ci.yml @@ -0,0 +1,101 @@ +name: backend-pr-ci + +on: + pull_request: + paths: + - "backend/**" + - ".github/workflows/backend-pr-ci.yml" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: backend-pr-ci-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +env: + GO_VERSION: "1.24" + +jobs: + lint: + name: Lint + runs-on: ubuntu-latest + timeout-minutes: 10 + + defaults: + run: + working-directory: backend + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version: ${{ env.GO_VERSION }} + cache-dependency-path: backend/go.sum + + - name: Install golangci-lint + run: go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest + + - name: Run golangci-lint + run: golangci-lint run --timeout=5m + + build: + name: Build + runs-on: ubuntu-latest + timeout-minutes: 10 + + defaults: + run: + working-directory: backend + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version: ${{ env.GO_VERSION }} + cache-dependency-path: backend/go.sum + + - name: Build WASM + run: GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o github.wasm . + + test: + name: Tests + runs-on: ubuntu-latest + timeout-minutes: 15 + + defaults: + run: + working-directory: backend + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version: ${{ env.GO_VERSION }} + cache-dependency-path: backend/go.sum + + - name: Run tests (race detector) + run: go test -race -timeout 60s -coverprofile=coverage.out $(go list ./...) + + - name: Upload coverage report + uses: actions/upload-artifact@v4 + with: + name: coverage-report + path: backend/coverage.out + retention-days: 7 diff --git a/.github/workflows/frontend-pr-ci.yml b/.github/workflows/frontend-pr-ci.yml new file mode 100644 index 0000000..8798bad --- /dev/null +++ b/.github/workflows/frontend-pr-ci.yml @@ -0,0 +1,53 @@ +name: frontend-pr-ci + +on: + pull_request: + paths: + - "frontend/**" + - ".github/workflows/frontend-pr-ci.yml" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: frontend-pr-ci-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + web-quality: + name: Typecheck and build frontend + runs-on: ubuntu-latest + timeout-minutes: 20 + + defaults: + run: + working-directory: frontend + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Setup Bun + uses: oven-sh/setup-bun@v2 + with: + bun-version: "1.2.23" + + - name: Cache Bun packages + uses: actions/cache@v4 + with: + path: ~/.bun/install/cache + key: ${{ runner.os }}-bun-${{ hashFiles('frontend/bun.lock') }} + restore-keys: | + ${{ runner.os }}-bun- + + - name: Install dependencies + run: bun install --frozen-lockfile + + - name: Typecheck + run: bun run typecheck + + - name: Build production bundle + run: bun run build diff --git a/.github/workflows/mcp-pr-ci.yml b/.github/workflows/mcp-pr-ci.yml new file mode 100644 index 0000000..1429198 --- /dev/null +++ b/.github/workflows/mcp-pr-ci.yml @@ -0,0 +1,53 @@ +name: mcp-pr-ci + +on: + pull_request: + paths: + - "mcp/**" + - ".github/workflows/mcp-pr-ci.yml" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: mcp-pr-ci-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + mcp-quality: + name: Typecheck and build MCP server + runs-on: ubuntu-latest + timeout-minutes: 10 + + defaults: + run: + working-directory: mcp + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Setup Bun + uses: oven-sh/setup-bun@v2 + with: + bun-version: "1.2.23" + + - name: Cache Bun packages + uses: actions/cache@v4 + with: + path: ~/.bun/install/cache + key: ${{ runner.os }}-bun-mcp-${{ hashFiles('mcp/bun.lock') }} + restore-keys: | + ${{ runner.os }}-bun-mcp- + + - name: Install dependencies + run: bun install --frozen-lockfile + + - name: Typecheck + run: bun run typecheck + + - name: Build + run: bun run build diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..540f827 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,93 @@ +name: Build and Release Plugin Assets + +on: + push: + tags: + - "v*" + workflow_dispatch: + +permissions: + contents: write + +jobs: + build-and-release: + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version: "1.24" + + - name: Setup Bun + uses: oven-sh/setup-bun@v2 + with: + bun-version: latest + + - name: Build backend WASM + working-directory: backend + run: | + set -euo pipefail + mkdir -p ../release/backend + GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o ../release/backend/github.wasm . + + - name: Build frontend + working-directory: frontend + run: | + set -euo pipefail + bun install --frozen-lockfile + bun run build + + - name: Build MCP + working-directory: mcp + run: | + set -euo pipefail + bun install --frozen-lockfile + bun run build + + - name: Collect release files + run: | + set -euo pipefail + mkdir -p release/frontend + cp -R frontend/dist release/frontend/dist + + mkdir -p release/mcp + cp -R mcp/dist release/mcp/dist + + mkdir -p release/migrations + cp -R backend/migrations/. release/migrations/ + + cp plugin.json release/plugin.json + + - name: Create archives + run: | + set -euo pipefail + tar -czf github-backend-wasm.tar.gz -C release/backend github.wasm + tar -czf github-frontend-dist.tar.gz -C release/frontend dist + tar -czf github-mcp-dist.tar.gz -C release/mcp dist + tar -czf github-migrations.tar.gz -C release migrations + tar -czf github-plugin-manifest.tar.gz -C release plugin.json + + - name: Generate checksums + run: | + set -euo pipefail + sha256sum github-backend-wasm.tar.gz \ + github-frontend-dist.tar.gz \ + github-mcp-dist.tar.gz \ + github-migrations.tar.gz \ + github-plugin-manifest.tar.gz > checksums.txt + + - name: Publish GitHub Release assets + uses: softprops/action-gh-release@v2 + with: + generate_release_notes: true + files: | + github-backend-wasm.tar.gz + github-frontend-dist.tar.gz + github-mcp-dist.tar.gz + github-migrations.tar.gz + github-plugin-manifest.tar.gz + checksums.txt From 67cb86fb4a4bffb5ac64b299bd51f380274b411b Mon Sep 17 00:00:00 2001 From: pikann Date: Wed, 13 May 2026 18:37:54 +0700 Subject: [PATCH 2/2] feat: add README.md with plugin architecture, API endpoints, and CI/CD details --- README.md | 177 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..058965c --- /dev/null +++ b/README.md @@ -0,0 +1,177 @@ +# com.paca.github + +First-party Paca plugin that integrates GitHub repositories, pull requests, and branches with projects and tasks. + +This plugin lets a project connect a GitHub token, link repositories, attach pull requests to tasks, create task branches, and receive GitHub webhooks for automatic sync. + +--- + +## Architecture + +The plugin follows the standard three-part structure: + +``` +paca-plugin-github/ +├── backend/ — Go WASM plugin (API host runtime) +├── frontend/ — React micro-frontend (Module Federation remote) +└── mcp/ — MCP tools (plugin-sdk-mcp) +``` + +### Backend (`backend/`) + +- Written in Go and compiled to `wasip1/wasm` for production. +- Registered as `com.paca.github`. +- Stores integration/repository/task-link data in plugin-owned tables (see migration `backend/migrations/0001_create_github_tables.sql`). +- Encrypts GitHub token and webhook secret using plugin config (`ENCRYPTION_KEY`). +- Creates/deletes GitHub webhooks for linked repositories. +- Subscribes to events: + - `task.deleted` to clean up task branch and PR links. + - `project.deleted` to clean up integration data. + +### Frontend (`frontend/`) + +- Vite + React + TanStack Query. +- Exposes task/project GitHub UI through extension points declared in `plugin.json`. +- Communicates with backend through plugin API routes under: + - `/api/v1/plugins/com.paca.github/projects/:projectId/...` + +### MCP (`mcp/`) + +- Built with `@paca-ai/plugin-sdk-mcp`. +- Exposes GitHub integration tools for agents and automation workflows. + +--- + +## Backend API Endpoints + +All routes are project-scoped by the host unless marked as public. + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/github` | Get current GitHub integration status | +| `POST` | `/github/token` | Set or replace GitHub personal access token | +| `DELETE` | `/github/token` | Remove token and integration | +| `GET` | `/github/repositories` | List GitHub repositories accessible by token | +| `GET` | `/github/linked-repositories` | List repositories linked to this project | +| `POST` | `/github/linked-repositories` | Link a repository and create webhook | +| `DELETE` | `/github/linked-repositories/:repoId` | Unlink repository and delete webhook | +| `GET` | `/tasks/:taskId/github/pull-requests` | List pull requests linked to a task | +| `POST` | `/tasks/:taskId/github/pull-requests` | Link a pull request to a task | +| `DELETE` | `/tasks/:taskId/github/pull-requests/:prId` | Unlink a pull request from a task | +| `POST` | `/tasks/:taskId/github/branches` | Create and link a branch for a task | +| `GET` | `/tasks/:taskId/github/branches` | List branches linked to a task | +| `POST` | `/webhook` | Public GitHub webhook endpoint | + +Webhook behavior: +- `pull_request` updates PR cache and can auto-link PRs when branch-task links exist. +- `push` can auto-link branches to tasks when branch names include task references like `PROJ-42`. + +--- + +## Frontend Extension Points + +| Extension Point | Component | Label | Order | +|-----------------|-----------|-------|-------| +| `project.settings.tab` | `GitHubSettingsTab` | `GitHub` | `100` | +| `task.detail.section` | `GitHubTaskSection` | - | `5` | + +Remote entry URL: + +`/plugins/com.paca.github/assets/remoteEntry.js` + +--- + +## MCP Tools + +The MCP package provides the following tools: + +- `github_get_integration` +- `github_set_token` +- `github_delete_token` +- `github_list_repositories` +- `github_list_linked_repos` +- `github_link_repository` +- `github_unlink_repository` +- `github_list_task_prs` +- `github_link_pr_to_task` +- `github_unlink_pr_from_task` +- `github_create_branch` +- `github_list_task_branches` + +--- + +## Development + +### Backend + +```bash +cd backend + +# Run tests +go test ./... + +# Build WASM (requires Go 1.24+) +GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o github.wasm . +``` + +### Frontend + +```bash +cd frontend + +# Install dependencies +bun install + +# Typecheck +bun run typecheck + +# Development build (watch) +bun run dev + +# Production build +bun run build +``` + +### MCP + +```bash +cd mcp + +# Install dependencies +bun install + +# Typecheck +bun run typecheck + +# Production build +bun run build +``` + +--- + +## CI/CD + +This repository includes GitHub Actions workflows under `.github/workflows`: + +- `backend-pr-ci.yml`: runs backend lint, build, and tests on backend-related PR changes. +- `frontend-pr-ci.yml`: runs frontend typecheck and build on frontend-related PR changes. +- `mcp-pr-ci.yml`: runs MCP typecheck and build on MCP-related PR changes. +- `release.yml`: builds backend/frontend/mcp artifacts on tag pushes (`v*`) and publishes release assets. + +Release artifacts include: + +- `github-backend-wasm.tar.gz` +- `github-frontend-dist.tar.gz` +- `github-mcp-dist.tar.gz` +- `github-migrations.tar.gz` +- `github-plugin-manifest.tar.gz` +- `checksums.txt` + +--- + +## Required Backend Config + +The backend uses the following allowed config keys defined in `plugin.json`: + +- `ENCRYPTION_KEY` for token/secret encryption. +- `PUBLIC_URL` for generating public webhook callback URLs. \ No newline at end of file