# cicd

**Repository Path**: jungle/cicd

## Basic Information

- **Project Name**: cicd
- **Description**: No description available
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-21
- **Last Updated**: 2026-05-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Simple CI/CD Service (Built with FastAPI)

## Core Features

- **Automated Git Repository Build & Deploy**: Submit a Git repository URL and the service automatically clones, builds, and deploys it (supports Dockerfile or custom build commands/ci_build.sh)
- **Single Sign-On (SSO)**: Integrates with a centralized authentication service using Cookie-based authentication
- **User Permission Control**:
  - **Regular Users**: Subject to job creation quota limit (default 2), can only operate on tasks they created
  - **Administrator Users**: Can operate on all tasks, no quota limit
- **User Management System**: Supports user profiles, avatar display, and quota management
- **Real-time Task Status**: Frontend automatically polls task status every 5 seconds without manual page refresh
- **Real-time Logs**: Incremental log streaming via WebSocket
- **Task History**: Records task execution history, runtime duration, and other metadata

## Recent Updates (April 2026)

- ? **User Profile Management**: UserProfile table with avatar URL, role, quota, registration time support
- ? **Task Creator Tracking**: Each task records created_by field, displaying creator name and avatar
- ? **Job Quota System**: Regular users have default quota limit (2 jobs), exceeding returns "insufficient quota" error
- ? **Fine-grained Permissions**: owner_or_admin authorization model - task creator or admin can edit/execute/delete tasks
- ? **Auto Status Refresh**: Task list status automatically refreshes every 5 seconds without manual page reload
- ? **English UI Localization**: User list, buttons, tooltips all switched to English
- ? **Service Footer Info**: Displays application version, uptime duration, and copyright information
- ? **Avatar Display**: Shows creator avatar in task list, supports parsing from multiple auth center fields

## Quick Start

### 1. Install Dependencies

\\\ash
python -m pip install -r requirements.txt
\\\

### 2. Start Service (Development Mode)

It's recommended to use \python -m uvicorn\ in a virtual environment to avoid issues with uvicorn executable recognition on PowerShell/Windows:

\\\ash
# Install dependencies (if not already installed)
python -m pip install -r requirements.txt
# Or install uvicorn only
python -m pip install "uvicorn[standard]"

# Start service (using python -m ensures module availability)
python -m uvicorn app.main:app --reload --reload-exclude "repos/*" --reload-exclude "artifacts/*" --host 0.0.0.0 --port 8000
\\\

**Note (PowerShell)**: To prevent shell wildcard expansion, wrap \--reload-exclude\ paths in quotes as shown above.

### 3. Production Deployment with Redis + RQ

\\\ash
docker-compose up --build
\\\

This starts \
edis\, \web\ (FastAPI), and \worker\ (RQ worker) services.

## Environment Configuration

The service loads \.env\ from the project root on startup. Restart the API and worker after modifying \.env\.

### Common Environment Variables

\\\dotenv
CICD_REPOS_ROOT=D:\\ci_workspace\\repos
CICD_ARTIFACTS_ROOT=D:\\ci_workspace\\artifacts

# Auth center URL for server-side /api/auth/session calls
AUTH_CENTER_URL=http://127.0.0.1

# Login page URL for unauthenticated redirects
AUTH_LOGIN_URL=http://127.0.0.1/enter
\\\

## Authentication & Authorization

- When accessing the CICD page without login, the browser is redirected to \AUTH_LOGIN_URL?next=current_url\
- The CICD backend forwards \cookieOnlineJudgeToken\ and \cookieOnlineJudgeUsername\ to the auth center's \/api/auth/session\ endpoint for validation
- Auth center returning \dmin=true\ indicates admin privileges; in current implementation, either \HEAD\ or \ADMIN\ permission grants admin status
- **Non-admin users**: Read-only access to task lists, details, logs, and artifacts
- **Admin users**: Can create, edit, re-execute, cancel, delete, restore, and clean up tasks

## Usage Examples

### Submit a Build Job

\\\ash
curl -X POST "http://localhost:8000/jobs" \\
  -H "Content-Type: application/json" \\
  -d '{"git_url":"https://github.com/your/repo.git"}'

Notes:
- You can optionally set `branch` to define which branch will be checked out when the job runs (default: `master`).
- To restrict which branches can re-queue a job via webhook, set `branch_filter` when creating/editing the job to a comma-separated list of patterns (e.g. `main,release/*`). An empty `branch_filter` means all branches are accepted.
\\\

### Query Job Status

\\\ash
curl http://localhost:8000/jobs/1
\\\

### Notes

- If the repository contains a \Dockerfile\, the service attempts to build and run the Docker image (requires Docker on the host)
- Custom build commands can be specified via the \uild_command\ field (e.g., \./build.sh\, \
pm ci && npm run build\)
- If auth center is enabled, write operations require an authenticated browser session with admin privileges or appropriate Cookie headers

### WebSocket Log Subscription

\\\
ws://127.0.0.1:8000/jobs/{id}/ws
\\\

### Cancel a Running Job

\\\ash
curl -X POST http://localhost:8000/jobs/1/cancel
\\\

## Production Deployment Guide

### 1. Auth Center & Cookie Domain

If CICD and auth center are deployed in different subdomains under the same parent domain, set Cookie Domain to the parent domain itself (e.g., \happyoj.com\), not using the leading-dot notation (\.happyoj.com\).

### 2. CICD SSO Configuration

Configure CICD to integrate with the auth center via \.env\:

\\\dotenv
AUTH_CENTER_URL=https://happyoj.com
AUTH_LOGIN_URL=https://happyoj.com/enter
\\\

### 3. Reverse Proxy & HTTPS

- Production deployments should run FastAPI and auth center behind Nginx / Caddy / Apache
- All browser traffic should use HTTPS consistently
- The reverse proxy must pass through the real Host header

### 4. Redis & Worker

- Development: Optional Redis, service falls back to local thread execution
- Production: Enable Redis + dedicated worker

### 5. Directories & Persistence

\
epos\ and \rtifacts\ should be placed outside the project directory and mounted to persistent storage:

\\\dotenv
CICD_REPOS_ROOT=/data/cicd/repos
CICD_ARTIFACTS_ROOT=/data/cicd/artifacts
\\\

### 6. Permission Model

- **Authenticated Regular Users**: Read-only
- **Users with \dmin=true\**: Full write access
- All write endpoints validated server-side

### 7. Troubleshooting

- **\.env\ changes not taking effect**: Check if API/worker have been restarted
- **Cookie domain errors**: Verify auth center is not using \.happyoj.com\
- **Stuck on login page**: Verify auth center's \/api/auth/session\ endpoint is accessible

### 8. WebSocket Handshake (Important for Live Logs)

If browser console shows `WebSocket connection ... failed` and a direct check to `/jobs/{id}/ws` returns `HTTP 404`, the reverse proxy is likely forwarding the request as plain HTTP instead of WebSocket upgrade.

Use Nginx HTTP/1.1 upgrade forwarding:

```nginx
map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}

server {
  listen 443 ssl;
  server_name cicd.happyoj.com;

  location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_read_timeout 3600;
  }
}
```

After updating Nginx, reload it and verify handshake:

```bash
curl -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
  https://cicd.happyoj.com/jobs/6/ws
```

Expected: status `101 Switching Protocols`.