# cicd

**Repository Path**: jungle/cicd

## Basic Information

- **Project Name**: cicd
- **Description**: Simple CI/CD Service (Built with FastAPI)
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://cicd.happyoj.com
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: cicd, pipeline

## README

# Simple CI/CD Service

A FastAPI-based CI/CD service for building Git repositories, running ordered or parallel
pipeline stages, dispatching stages to remote agents, streaming logs, collecting artifacts,
and publishing downloadable releases. The web UI is served by the same application.

## 1. Features

- Create and manage build jobs from the web UI or API.
- Clone a repository and run custom stages, a Dockerfile build, a CMake build,
  or a repository-provided `ci_build.sh`.
- Run stages locally or dispatch them to remote agents. Leave agent targeting empty to run a
  stage on the CI/CD server. Stages in the same wave run concurrently; waves run in order.
- Configure an ordered list of agents for a stage. Offline, full, or otherwise unavailable
  candidates are skipped before a task is accepted.
- Stream build logs to the job page and retain per-run logs, status, duration, and commit data.
- Collect artifacts per run, download them, and publish finished runs as public releases.
- Manage Python build plugins, local user accounts (in bypass mode), agents, and user access
  from the web UI.
- Trigger builds with Gitee/GitHub push webhooks (one auto-detected URL, extensible to other
  vendors with a declarative provider file) or per-job cron/interval schedules.

## 2. Requirements

- Python 3.11 or later for the service (the Docker image and CI use Python 3.11).
- Git on the server. Build tools required by your repositories must also be installed.
- Docker Engine and a reachable Docker daemon only if you use repository `Dockerfile` builds.
- Python 3.8 or later on remote agent machines.
- Redis is optional. The default configuration uses the service's built-in local worker and
  does not require Redis.

## 3. Quick start

Run these commands from the repository root.

### 3.1 Windows PowerShell

```powershell
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
Copy-Item example.env .env
```

Edit `.env` before starting the service. For a local-only development instance, the checked-in
example enables bypass authentication and includes example credentials. Change those values
before use, and never expose bypass mode to an untrusted network.

```powershell
python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
```

### 3.2 Linux or macOS

```bash
python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
cp example.env .env
```

Edit `.env`, then start the development server:

```bash
python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
```

Open <http://127.0.0.1:8000/>. FastAPI's interactive API documentation is available at
<http://127.0.0.1:8000/docs>.

### 3.3 Docker Compose

The repository's Compose file is a development example that builds and starts the web
container:

```bash
docker compose up --build
```

It publishes port `8000`, bind-mounts the source directory at `/app`, and does not start
Redis or an RQ worker. Before using it, edit `.env` for paths inside the Linux container;
the Windows paths in `example.env` are not valid container paths. The Compose file does not
mount the default temporary repository/artifact/release/plugin directories, so configure
and mount persistent storage before relying on them across container recreation. Dockerfile
build jobs also need the container to be configured to reach a Docker daemon; the example
Compose file does not provide that connection.

The server applies database migrations during startup. To apply them manually:

```bash
python -m app.apply_migrations
```

The default SQLite database is `cicd.db` in the working directory. Keep repository checkouts,
artifacts, uploaded plugins, and published releases outside the project directory, especially
when using `--reload`. The example environment file shows Windows-style paths; update them for
your operating system.

## 4. Configuration

The application loads `.env` during startup. Restart the API after changing configuration.
When running a separate compatible worker, restart that process as well.

### 4.1 Service, database, and storage

| Variable | Default | Purpose |
| --- | --- | --- |
| `DATABASE_URL` | `sqlite:///./cicd.db` | SQLAlchemy database URL. SQLite is the default. |
| `CICD_REPOS_ROOT` | System temp directory + `cicd_repos` | Cloned repositories, run logs, and build workspaces. |
| `CICD_ARTIFACTS_ROOT` | System temp directory + `cicd_artifacts` | Build artifacts and agent uploads. |
| `CICD_RELEASES_ROOT` | System temp directory + `cicd_releases` | Published release files. Keep this outside `CICD_ARTIFACTS_ROOT`; artifact cleanup must not remove releases. |
| `CICD_PLUGINS_ROOT` | System temp directory + `cicd_plugins` | Uploaded plugin source files. Built-in plugins are shipped with the application. |
| `CICD_WEBHOOK_PROVIDERS_ROOT` | System temp directory + `cicd_webhook_providers` | Declarative webhook provider files (`*.json`), loaded at startup. Keep it outside the project tree so `--reload` does not restart mid-build. |
| `REDIS_URL` | Unset | Optional Redis connection for Redis-backed queue/pub-sub integration. See the worker note below. |

For a durable installation, configure persistent storage paths. The service creates these
directories when needed. Back up the database and persistent storage as part of operations.

Example:

```dotenv
DATABASE_URL=sqlite:///D:/ci-data/cicd.db
CICD_REPOS_ROOT=D:/ci-data/repos
CICD_ARTIFACTS_ROOT=D:/ci-data/artifacts
CICD_RELEASES_ROOT=D:/ci-data/releases
CICD_PLUGINS_ROOT=D:/ci-data/plugins
CICD_WEBHOOK_PROVIDERS_ROOT=D:/ci-data/webhook-providers
```

SQLite URL syntax varies by platform. For a Windows absolute path, use
`sqlite:///D:/path/to/cicd.db`; for a Unix absolute path, use
`sqlite:////var/lib/cicd/cicd.db`.

### 4.2 Authentication

| Variable | Default | Purpose |
| --- | --- | --- |
| `AUTH_DISABLED` | `0` | Set to `1` only for local-account/bypass mode. |
| `AUTH_CENTER_URL` | `http://localhost` | SSO service base URL; the application validates its session endpoint. |
| `AUTH_LOGIN_URL` | `http://localhost/enter` | Login page used by the SSO integration. |
| `AUTH_LOGOUT_URL` | Unset | Optional SSO logout URL. When unset, logout is local to this service. |
| `AUTH_BYPASS_USERNAME` | `dev` | Built-in account name in bypass mode. |
| `AUTH_BYPASS_ADMIN` | `1` | Whether the built-in bypass account is an administrator. |
| `AUTH_BYPASS_PASSWORD` | Empty | Password for the built-in bypass account. An empty value disables its login. |
| `AUTH_BYPASS_SECRET` | Unset | Stable signing secret for bypass-mode sessions. Falls back to `WEBHOOK_SECRET`, then a process-random secret. |
| `AUTH_BYPASS_SESSION_TTL` | `43200` | Maximum session lifetime in seconds when “Remember me” is not selected. |
| `AUTH_BYPASS_REMEMBER_TTL` | `2592000` | Session lifetime in seconds when “Remember me” is selected. |

Use SSO mode for a trusted production deployment. Set `AUTH_CENTER_URL` and `AUTH_LOGIN_URL`
to the actual authentication service. In bypass mode, set `AUTH_DISABLED=1` and a strong
`AUTH_BYPASS_PASSWORD`. Local users can then register from the login dialog; new accounts are
regular users and an administrator can manage them from the Users page.

If bypass mode runs in a multi-process deployment, set a stable `AUTH_BYPASS_SECRET` so
sessions can be verified consistently. Do not rely on the process-random fallback.

### 4.3 Webhooks and build execution

| Variable | Default | Purpose |
| --- | --- | --- |
| `WEBHOOK_SECRET` | Unset | Fallback verification secret when a job has no job-specific one: the Gitee token, the GitHub HMAC-SHA256 secret, or the token/signature secret of an installed provider. |
| `CICD_ENABLE_TIMEOUTS` | `1` | Enables the default command timeout. |
| `CICD_CMD_TIMEOUT` | `600` | Default build-stage command timeout in seconds. A stage can set its own timeout. |
| `CICD_STAGE_AGENT_TIMEOUT` | `3600` | Default wait limit for a stage dispatched to an agent. A stage can set its own timeout. |
| `CICD_DETACH_STARTUP_SECONDS` | `5` | Time to capture startup output for a detached stage. |
| `CICD_TOOLCHAIN_CC` | `gcc` | Compiler name exposed to build stages. |
| `CICD_TOOLCHAIN_CXX` | `g++` | C++ compiler name exposed to build stages. |
| `CICD_TOOLCHAIN_CMAKE_GENERATOR` | `MinGW Makefiles` | CMake generator setting for configured toolchain environments. |
| `CICD_TOOLCHAIN_MSYS_PATHS` | `D:\msys64\mingw64\bin;D:\msys64\usr\bin` | Windows MSYS2 paths added to the toolchain environment. |
| `CICD_TOOLCHAIN_PROBE_CMD` | Unset | Optional command used to check toolchain availability. |
| `CLEANUP_ENABLED` | `1` | Enables periodic cleanup of expired soft-deleted jobs and old artifact runs. |
| `CLEANUP_INTERVAL_SECONDS` | `86400` | Periodic cleanup interval. |
| `CLEANUP_RETENTION_DAYS` | `30` | Age after which soft-deleted jobs may be permanently removed. |
| `CICD_ARTIFACT_KEEP_RUNS` | `5` | Number of recent artifact runs to retain for each job. |
| `AUTO_SCHEDULE_ENABLED` | `1` | Enables the background auto-schedule runner. |
| `AUTO_SCHEDULE_TICK_SECONDS` | `30` | Auto-schedule polling interval; values below 5 are raised to 5. |
| `CICD_PLUGIN_MAX_BYTES` | `131072` | Maximum uploaded plugin source size in bytes. |
| `CICD_PLUGIN_TEST_TIMEOUT` | `30` | Plugin editor test-run timeout in seconds (clamped to 300 seconds). |

Set `CICD_ENABLE_TIMEOUTS=0` to disable the default command timeout. Explicit per-stage
timeouts still apply. Plugin test runs always have a bounded timeout.

Cleanup is enabled by default. Its job-retention setting applies to soft-deleted jobs;
`CICD_ARTIFACT_KEEP_RUNS` separately limits each job's retained build artifacts. Published
releases are stored separately and are not removed by artifact retention.

### 4.4 Remote agent settings

Agents are normally configured using the **New Agent** flow on the Agents page. The generated
startup command registers the agent and sets its service URL, label, one-time token, and
capacity. Keep that command private until it has been used.

The standalone agent also accepts these environment variables:

| Variable | Default | Purpose |
| --- | --- | --- |
| `CICD_SERVICE_URL` | `http://localhost:8000` | Service base URL. |
| `CICD_AGENT_NAME` | Machine hostname | Agent's displayed name. |
| `CICD_AGENT_LABEL` | Unset | Primary routing label. |
| `CICD_AGENT_LABELS` | Unset | Comma-separated capabilities/labels. |
| `CICD_AGENT_CAPACITY` | `1` | Maximum concurrent tasks on the agent. |
| `CICD_AGENT_WORK_ROOT` | System temp directory + `cicd_agent_work` | Root directory for agent task workspaces. |
| `CICD_AGENT_HEARTBEAT_INTERVAL` | `20` | Heartbeat interval in seconds. |
| `CICD_AGENT_ARTIFACT_GLOB` | `artifacts/*` | Agent-side artifact collection pattern. |
| `CICD_AGENT_LOG_LEVEL` | `INFO` | Agent log level. |
| `CICD_AGENT_LOG_FILE` | `<install root>/agent.log`, or `<work root>/agent.log` when run from a checkout | Persistent agent log. Always written unless the path is unwritable; console output is kept too. |
| `CICD_AGENT_LOG_MAX_BYTES` | `10485760` (10 MiB) | Size at which the agent log rotates. |
| `CICD_AGENT_LOG_BACKUPS` | `5` | Number of rotated agent log files kept. |

The agent writes its log to a rotating file beside its install (`agent_state.json`'s directory)
so the log survives version switches and is still there when the agent was started in the
background. Set `CICD_AGENT_LOG_LEVEL=DEBUG` to include every line a task printed; at `INFO`
the agent's own milestones and the generated stage script's `[agent-stage]`/`[toolchain]`
diagnostics are recorded, while the full build output is streamed to the job log as before.
A failing log file never stops the agent — it falls back to console output. Agent-side stage
diagnostics are also stamped as they are emitted, e.g.
`[2026-10-23 09:15:02] [agent:build-01] [agent-stage] restore build bundle start ...`, so a
line in the job log says which machine produced it and when. Build command output is relayed
unchanged.

The agent also accepts `CICD_AGENT_API_KEY`, `CICD_AGENT_TOKEN`, `CICD_AGENT_VERSION`, and
`CICD_AGENT_INSTALL_ROOT`; these are normally managed by the generated startup process.
Bootstrapped agents can be upgraded manually from the Agents page. Agents started directly
from a source checkout do not support self-upgrade.

### 4.5 Optional S3 integrations

S3 support is optional and has two separate configuration paths. `S3_BUCKET` and optional
`S3_PREFIX` make the job-artifact download endpoint return a presigned GET URL instead of a
local file response; this expects the matching objects to exist in that bucket/key layout.
`CICD_S3_BUCKET` enables the agent artifact-upload presign endpoint, which creates a key under
`host_<hostname>/task_<task_id>/`. Both paths use the AWS SDK's configured credential chain
and require `boto3` plus appropriate IAM permissions. Without a working presigned upload,
agents fall back to the service's regular upload endpoint. These settings do not configure
the database, repository checkout, or release storage.

## 5. Creating and running builds

Use **New Build** in the web UI to configure a repository, branch, visibility, credentials,
stages, webhooks, and schedules. A job's default branch is `master`; its default visibility is
private. Jobs are owned by their creator. Owners and administrators can manage a job, and a
private job can be shared with explicitly allowed users. Regular users have a default quota of
two non-deleted jobs they own; administrators are not subject to that quota.

When code download is enabled, the service performs a shallow clone of the selected branch.
Build behavior is selected in this order:

1. If custom stages are configured, the service runs those stages.
2. Otherwise, a repository `Dockerfile` is built and its container is started (requires a
   configured Docker daemon).
3. Otherwise, a repository containing `CMakeLists.txt` is configured and built with CMake.
4. Otherwise, `ci_build.sh` is run with Bash.

If none of these build methods is available, the job fails with a “nothing to do” build error.
The build page's **Help** tab renders this README. The **Pipeline** preview API is an
administrator-only inspection tool; it can inspect supported repository YAML metadata but
does not execute YAML pipeline files. `app/static/pipeline.example.yml` is an example, not an
active build mode.

When **Prepare/download code** is disabled, the service skips the clone and uses the
job-and-branch workspace already on disk. It does not guarantee that workspace is empty or
matches the current remote branch, so use this option only when you intentionally manage that
workspace. A source archive cannot be made from a run that has no matching checked-out commit.

### 5.1 Custom stages

Each stage needs a name and either a shell command or a plugin. For example:

```json
{
  "git_url": "https://example.com/team/project.git",
  "branch": "main",
  "custom_stages": [
    {
      "name": "build",
      "command": "cmake -S . -B build && cmake --build build",
      "artifact_dir": "build",
      "group": 1
    },
    {
      "name": "test",
      "command": "ctest --test-dir build",
      "group": 2,
      "agent_labels": ["linux-builder", "linux-backup"]
    }
  ]
}
```

Stages with the same positive `group` value run in parallel; groups run in ascending order.
A stage without a positive group uses its position in the stage list as its group number. As a
result, an explicitly assigned group number can coincide with an ungrouped stage's position.
`artifact_dir` collects output from a local stage. For compatibility, a legacy/API-defined
stage with no agent target runs on the server; new stages in the editor must select **Local**
explicitly to do so. An `agent_labels` array is tried in order, skipping an agent that is
offline, full, or cannot be used. A single legacy `agent_label` is also accepted.

The Agents page lists **Locally on the CI/CD server** as a built-in agent by default. It shares
the agent table and stage picker with remote agents; only administrators can edit its settings,
and it has no reconnect or delete action. Administrators can enable or disable Local execution
and choose whether it is available to all users or only to named users. Administrators remain
authorized while Local is enabled. Its row reports the service version and detected tool
versions; unavailable tools are omitted from the detected-version list.

The stage editor exposes additional settings such as timeout, detached execution, and artifact
filename. A local `artifact_dir` can name a file or directory; directories are archived as
`.tar.gz`. `artifact_name` can override the collected filename. Agent stages use
`CICD_STAGE_AGENT_TIMEOUT` as their default wait limit; local commands use
`CICD_CMD_TIMEOUT` when timeouts are enabled. An explicit stage timeout applies to that stage.
A detached command stage reports whether it started successfully; it is not suitable for
plugin stages. Stage commands run in the repository workspace, with service credentials
filtered from their environment.

Plugin-stage parameters may be bound to prior-stage output instead of using literal values:

```json
{
  "name": "publish",
  "type": "plugin",
  "plugin": "release-publisher",
  "params": {
    "version": {"from": "log", "key": "VERSION"},
    "package_name": {"from": "file", "path": ".cicd/package.json", "key": "name"}
  }
}
```

An earlier stage publishes a log value by printing `::cicd-set VERSION=1.2.3`. Log bindings
are resolved from the current run's log. File bindings read a JSON file in the repository
workspace and may therefore work when the earlier stage ran on an agent. Missing values or
files fail the stage with an explanation rather than passing an empty value.

### 5.2 Job, branch, and run lifecycle

Jobs are long-lived configurations; each execution creates a separate run with its own
branch, status, timestamps, commit information, log, and artifacts. Use a job's branch
selector to choose a branch, then start or re-run the job. **Build History** opens a specific
run's log and artifacts; the job-level log download always refers to the latest run. A
branch can have several historical runs, and branch-run deletion is separate from deleting
the job.

Use **Cancel** for a queued or running job. A locally executing command is terminated by the
server. There is no stop channel from the server to an agent after a remote task has been
dispatched: cancellation marks the job cancelled, but the remote process may continue until
it finishes. **Stop** is for a detached process started by a build, not a substitute for
canceling an ordinary stage. If an agent candidate is skipped before accepting a task, the
next configured candidate is tried; a task that was accepted and then fails is not
automatically retried on another agent.

Deleting a job from the UI is a soft delete; an owner or administrator can restore it.
Purge permanently removes the job and its artifact files. The cleanup runner permanently
removes aged soft-deleted jobs after `CLEANUP_RETENTION_DAYS`.

### 5.3 Git access and checkout behavior

The service performs shallow, single-branch checkouts, so only the selected branch's current
commit is guaranteed to be present. Use a read-only repository credential with the narrowest
scope possible for private repositories. The credential is not returned as a normal job
setting, but the authenticated clone URL is used as the checkout's Git remote; build code
that reads `.git/config` can therefore access it. Avoid printing Git remote configuration or
environment dumps in build output.

## 6. Remote agents

1. Open **Agents** and choose **New Agent**.
2. Set a name, routing label(s), and task capacity.
3. Run the generated startup command on a machine that can reach the service.
4. In a stage's **Execute on agent group** selector, choose one or more agents in priority
   order. Type in the selector to search by hostname, operating system, label, or toolchain.

Leave the stage's agent group empty to execute that stage on the server. Agent registration
tokens are temporary; the registered agent uses its API key for later requests. Agent
visibility can be public or private. A private agent can be used by its owner, an
administrator, or users explicitly listed in its sharing settings; only its owner or an
administrator can manage, delete, or upgrade it.

The server considers an agent live only while it is online and has sent a heartbeat within
60 seconds. Its configured capacity includes pending reservations as well as running tasks;
the agent polls only while it has a free slot and executes accepted tasks concurrently up to
that capacity. Remote stages routed to the same agent label can reuse that job-and-branch
workspace; a different agent has a different filesystem. To pass a file or directory from
one remote stage to a later remote stage on another agent, configure `artifact_dir` on the
producing stage; the successful task exports it and the later stage restores it. The ordered
agent list is a pre-dispatch fallback, not a retry policy: offline, full, inaccessible, or
otherwise unassignable agents are skipped, but a task failure after acceptance fails the
stage.

The generated command is the recommended installation method. For a source checkout, install
`requirements-agent.txt` and start the standalone process with
`python -m app.agents.agent --service-url <url> --token <registration-token> --label <label>`.
The registration token expires after 10 minutes by default and is consumed during
registration. Keep it and the returned startup command private; a registered agent's API key
authorizes its task and artifact operations. Treat agent machines as trusted build workers:
remote build code runs on them, and private-repository credentials are used for their
checkout.

Agent upgrades are initiated manually from the Agents page. Bootstrapped agents that advertise
self-upgrade install the requested version alongside the running one, finish in-flight tasks,
then restart. Older agents and agents started directly from a source checkout must be updated
by re-running their generated startup command. On Windows, a self-upgrade may return the
foreground console to its prompt while the replacement agent remains attached to that console.

## 7. Artifacts and releases

Artifacts are stored per job and per run beneath `CICD_ARTIFACTS_ROOT`. Build-stage artifacts
and agent uploads are listed against the run that produced them. By default, the cleanup
runner retains artifacts from the five newest runs of each job.

From a completed run, choose **Publish** to open a non-writing preview. Select a project name,
version, and the files to include. Candidates can include the run's recorded artifacts,
workspace output directories (`build/`, `dist/`, and `target/` when present), and a source
archive. The dialog selects available candidates by default; unchecking all candidates makes
the publish invalid. A source archive is created from the run's recorded commit and is
unavailable if the shallow workspace no longer has that commit. The source name can be
customized; it controls both the versioned archive filename and the folder name inside it.

A release copies selected files into `CICD_RELEASES_ROOT/<project>/`; project names cannot
contain path separators. Files are flat within each project and filenames are versioned
before their extensions (for example, `build.tar.gz` becomes `build-v1.2.3.tar.gz`). A
filename conflict blocks publishing rather than overwriting an existing file. Each file
stores a SHA-256 checksum, and downloads are counted per file and per release. Published
files are public and downloaded using `/releases/{project}/download?name=<filename>`; protect
the release root accordingly. Publishing and deletion require the job owner or an
administrator. Releases are separate copies and survive artifact cleanup and job deletion.

The artifacts page/API and the Releases page are distinct: artifact retention removes old
build outputs, while releases keep their copied files until a user deletes them. Jobs can also
be soft-deleted or purged without removing already-published releases.

The releases page is available at `/#releases`. The service version comes from the root
`VERSION` file and is also reported by `/service/info`.

## 8. Plugins

A plugin is one Python file with a literal module-level `PLUGIN` manifest and a module-level
`run(ctx)` entry point. Plugins can be selected as custom build stages. The Plugins page
includes built-in plugins and supports uploading, editing, and testing user plugins. Plugin
names must be lowercase slugs (letters, digits, `.`, `_`, and `-`; at most 64 characters),
and uploaded source must be UTF-8 and no larger than `CICD_PLUGIN_MAX_BYTES` (128 KiB by
default). The manifest is parsed without executing the file and requires a literal dictionary;
its name, version, description, and parameter declarations are stored with the plugin.

Example:

```python
import os

PLUGIN = {
    "name": "package-report",
    "version": "1.0.0",
    "description": "Write a build summary",
    "params": [
        {"name": "output", "type": "string", "required": True}
    ],
}

def run(ctx):
    ctx.log("Writing report")
    with open(os.path.join(ctx.workspace, ctx.get("output")), "w", encoding="utf-8") as report:
        report.write("Build completed\n")
    return 0
```

Supported parameter types are `string`, `text`, `number`, `boolean`, and `choice`. A stage
parameter declaration may include `name`, `type`, `label`, `description`, `required`,
`default`, and, for `choice`, a non-empty `options` list. In `run(ctx)`, use `ctx.workspace`,
`ctx.stage_name`, `ctx.job_id`, `ctx.run_id`, `ctx.get("parameter")`, and `ctx.params`; call
`ctx.log("message")` to write to the build log. `ctx.run(command, check=True, cwd=None,
env=None)` runs a command from the plugin and streams its output to the build log. Locally
executed plugins can also read `ctx.log.content` and `ctx.log.path`. Those log-file
properties are not available to an agent-executed plugin; use a log binding if the plugin
needs a value produced in the run log.

A stage parameter can also bind to a value published by an earlier stage or to a JSON file in
the workspace; see [Section 5.1](#51-custom-stages). Credentials must not be put in plugin
parameters: stage configuration is visible through the jobs API. There is no secret parameter
type.

The editor's **Test run** parses and runs the source currently in the editor without saving
it or creating a build. It uses a temporary empty workspace (no repository checkout) and a
bounded timeout. It is not a sandbox: a plugin has the same machine privileges as a build
command. Built-in plugins cannot be edited or deleted, though administrators may disable
them. Editing an uploaded plugin preserves its name, enabled state, and visibility; names
cannot be changed because saved stages refer to plugins by name. Private plugins are usable
only by their owner or an administrator. Built-in plugin source is readable; uploaded source
is readable only by its uploader or an administrator, even though the plugin catalog itself
is public.

Plugins execute as code with the same privileges as a stage command: on the server for a
local stage, or on the selected agent for a remote stage. Only install or enable plugin code
you trust. `CICD_PLUGIN_MAX_BYTES` limits source size; the editor's test run has a separate
bounded timeout and is not a sandbox.

## 9. Webhooks and schedules

Every job with webhooks enabled gets one URL. The vendor is detected from the request
headers, so the same URL works for Gitee, GitHub and installed providers:

```text
POST /webhooks?job_id=<job-id>
```

Explicit vendor paths also work, and are what hooks configured before auto-detection use:

```text
POST /webhooks/gitee?job_id=<job-id>      # X-Gitee-Token
POST /webhooks/github?job_id=<job-id>     # X-Hub-Signature-256 (HMAC-SHA256)
POST /webhooks/<provider>?job_id=<job-id>
```

Enable webhooks on the job and configure a per-job token/secret or `WEBHOOK_SECRET`. The same
value is the shared secret for whichever vendor sends the delivery:

- **Gitee**: select the Push event and send the token in `X-Gitee-Token`.
- **GitHub**: select the Push event, set Content type to `application/json`, and use the
  token as the webhook secret. GitHub signs the raw request body; the service verifies
  `X-Hub-Signature-256: sha256=<hex>`.

An optional comma-separated `branch_filter` accepts branch patterns such as
`main,release/*`; an empty filter accepts all branches. Webhook pushes re-queue the
configured job using the pushed branch. GitHub and declarative providers acknowledge and
ignore non-push events (`ping`, pull requests, ...); a tag push is ignored for every vendor.
Gitee keeps its historical behavior of processing any delivery that carries a branch ref.
If no secret is configured, deliveries are accepted without verification — configure one in
production. A job has one secret field, shared by every provider that delivers to it.

Auto-detection order is: built-in providers first (`gitee`, `github`), then installed
providers in filename order; the first header match wins. An explicit `/webhooks/<provider>`
path is authoritative and does not require detection headers. Repository matching normalizes
case, a trailing `/` and a trailing `.git`; an SSH URL (`git@...`) does not match the HTTPS
form a webhook sends.

### Third-party webhook providers

A vendor can be added without code changes: drop a JSON file into
`CICD_WEBHOOK_PROVIDERS_ROOT` and restart the service. Invalid files, duplicate names and
names colliding with built-ins are logged and skipped; built-ins can never be replaced. The
file is interpreted, never imported or executed, and its verification is limited to the
schemes below.

Example (`gitlab.json`):

```json
{
  "name": "gitlab",
  "display_name": "GitLab",
  "detect": {"headers_any": ["X-Gitlab-Event", "X-Gitlab-Token"]},
  "event": {"header": "X-Gitlab-Event", "push_events": ["Push Hook"]},
  "verify": {"type": "token", "header": "X-Gitlab-Token"},
  "fields": {
    "repo_url": ["project.git_http_url", "project.web_url", "repository.clone_url"],
    "repo_name": ["project.name", "project.path_with_namespace"],
    "ref": ["ref"],
    "after": ["after", "checkout_sha"],
    "deleted": ["deleted"],
    "pusher": ["user_name", "user.username"],
    "message": ["commits[0].message", "head_commit.message"]
  }
}
```

| Key | Meaning |
| --- | --- |
| `name` | Required. Slug (`a-z`, `0-9`, `_`, `-`); used as the route segment. |
| `detect.headers_any` | Any non-empty header selects this provider during auto-detection. |
| `detect.user_agent_prefixes` | Case-insensitive `User-Agent` prefix match (optional). |
| `event.header` / `event.push_events` | Event filter; omitted means every event is treated as a push. `event.case_sensitive` defaults to `false`. |
| `verify.type` | `token`, `hmac-sha256`, `hmac-sha1` or `none`. `none` with a configured secret fails closed (401). |
| `verify.header` / `prefix` / `encoding` | Secret/signature header; optional prefix such as `sha256=`; `hex` (default) or `base64`. |
| `fields.repo_url`, `fields.ref` | Required. Ordered dotted paths; the first non-empty value wins. List indices are supported (`commits[0].message`). |
| `fields.repo_name` / `after` / `deleted` / `pusher` / `message` | Optional mappings; an all-zero `after` is treated as a branch deletion. |
| `fields.ref_prefix` | Prepended when the extracted ref is not absolute (e.g. `refs/heads/`). |

Jobs can also be configured in the UI to run on a cron schedule or at a fixed interval.
The scheduler uses UTC. It does not enqueue another run while the job is already queued or
running; that scheduled occurrence is advanced rather than queued for later. The next run is
checked at `AUTO_SCHEDULE_TICK_SECONDS` intervals. `AUTO_SCHEDULE_ENABLED` controls the
service-wide scheduler.

## 10. Authentication and permissions

- SSO mode is the default. The service validates the authentication cookies with the configured
  auth center.
- Bypass mode is intended for local development or a deliberately self-hosted installation.
  Enable it with `AUTH_DISABLED=1`; configure the built-in account password and a persistent
  session secret.
- In bypass mode, users can register local accounts from the login dialog. New registrations
  are regular users. Administrators manage roles, quotas, account status, and password resets
  on the Users page.
- Role grants, suspension, and quota administration work in SSO mode. Local account
  registration, deletion, and password administration are bypass-mode features; SSO
  passwords remain with the authentication provider. Local accounts can change their own
  password and avatar in **Settings**. The built-in `.env` bypass account cannot be managed
  from Users.
- Local-account password reset/change invalidates existing local-account sessions. In SSO
  mode, signing out is local to this service unless `AUTH_LOGOUT_URL` is configured to sign
  out at the upstream auth center.
- Job writes are restricted to the owner, explicitly allowed users where supported, or an
  administrator. Agent and plugin use permissions are checked both when a job is saved and
  when its stage is dispatched.
- The Releases and Plugins pages are readable without signing in. Release mutations and
  plugin uploads require authentication.

Do not expose development bypass credentials or the service directly to an untrusted network.
Use HTTPS behind a reverse proxy for production, and configure the proxy to forward WebSocket
upgrade headers for live build logs.

## 11. Redis and background processing

Without `REDIS_URL`, the API starts a built-in local worker that claims queued jobs from the
database and runs them in background threads. Redis is not required for ordinary operation;
WebSocket log streaming falls back to database polling when Redis is unavailable.
Queue priority is meaningful for Redis/RQ queue selection. The built-in local worker claims
queued rows in database job-ID order, so do not rely on high/normal/low priority to reorder
local-mode jobs.

Although Redis/RQ integration code remains in the application, the current
`app/worker.py` is a placeholder and does not run an RQ worker. Do not set `REDIS_URL` expecting
that script to process jobs. Use the default local worker unless you have separately deployed
a compatible RQ worker for this codebase.

The root `docker-compose.yml` builds and starts the web application only. It does not start
Redis or an RQ worker.

## 12. Operations and troubleshooting

- Keep `CICD_REPOS_ROOT`, `CICD_ARTIFACTS_ROOT`, `CICD_RELEASES_ROOT`, and
  `CICD_PLUGINS_ROOT` on persistent storage, outside the source tree. Keep the releases root
  separate from the artifacts root.
- Ensure the service account can read and write its database and storage directories. The
  service needs Git; Docker builds additionally need access to a Docker daemon.
- `.env` values are loaded at process startup. Restart the API after changing them.
- If a job remains queued, check that the API startup worker is running and that Redis has not
  been configured without a compatible RQ worker.
- If an agent is not available for a stage, check its heartbeat, status, labels, capacity, and
  visibility/sharing permissions.
- If live logs do not update behind a reverse proxy, ensure it forwards HTTP/1.1 WebSocket
  upgrade headers.
- Published releases are not pruned by artifact retention. Delete unwanted releases from the
  Releases page or through the release API.

## 13. Development and tests

Install the dependencies and run the test suite from the repository root:

```bash
python -m pip install -r requirements.txt
python -m pytest -q
```

The CI workflow runs the test suite with coverage on Python 3.11.

## 14. API quick reference

For request and response schemas, use the live OpenAPI page at `/docs`. The main route
families are:

| Area | Routes | Purpose |
| --- | --- | --- |
| Jobs | `POST/GET /jobs`, `GET/PATCH/DELETE /jobs/{job_id}` | Create, list, inspect, edit, and soft-delete jobs. |
| Runs and branches | `/jobs/{job_id}/runs`, `/jobs/{job_id}/branches`, `/jobs/{job_id}/reexecute`, `/runs/{run_id}/logs` | Run history, branch history, re-execution, and run-specific logs. |
| Build controls | `/jobs/{job_id}/cancel`, `/jobs/{job_id}/stop`, `/jobs/{job_id}/undo_delete`, `/jobs/{job_id}/purge` | Cancel, stop detached work, restore, or permanently purge a job. |
| Live logs | WebSocket `/jobs/{job_id}/ws`, `/jobs/{job_id}/logs`, `/jobs/{job_id}/logs/download`, `/runs/{run_id}/logs/download` | Follow job logs or retrieve the latest job log or one run's log. |
| Artifacts | `/jobs/{job_id}/artifacts`, `/jobs/{job_id}/artifacts/download`, `/artifacts/{artifact_id}`, `/artifacts/cleanup` | List/download artifacts; administrator-only delete and cleanup operations. |
| Agents | `/hosts/`, `/hosts/options`, `/hosts/register`, `/hosts/temp_token`, `/hosts/upgrade`, `/hosts/agent/bootstrap`, `/hosts/agent/manifest`, `/hosts/agent/download/{version}` | Manage/register agents, retrieve routing options, and bootstrap/download agent packages. |
| Agent protocol | `/hosts/heartbeat`, `/hosts/poll`, `/hosts/result`, `/hosts/task_log`, `/hosts/artifacts/*` | Heartbeats, task polling/results/logs, and regular or resumable artifact upload. |
| Plugins | `/plugins`, `/plugins/source`, `/plugins/parse`, `/plugins/test`, `/plugins/{plugin_id}` | Browse and manage plugins, validate/test source, and update plugin settings. |
| Releases | `/jobs/{job_id}/runs/{run_id}/publish/preview`, `/jobs/{job_id}/runs/{run_id}/publish`, `/releases`, `/releases/projects`, `/releases/{project}/download` | Preview/publish, browse public release files, and download a named file. |
| Users and sessions | `/me`, `/users`, `/users/me/*`, `/users/{username}/*`, `/api/auth/logout`, `/api/auth/bypass/*` | Current-user information, administration, local-account settings, and authentication/logout in bypass mode. |
| Platform | `/jobs/bulk`, `/jobs/summary`, `/runs/{run_id}/stages`, `/runs/{run_id}/provenance`, `/runs/{run_id}/archive*`, `/releases/{release_id}/provenance` | Bulk actions, organization summary, persisted stage state, build provenance, and run archive/restore. |
| Operations | `/audit/events`, `/health/live`, `/health/ready`, `/system/stats`, `/system/cleanup/*`, `/hosts/scheduling`, `/hosts/tasks` | Audit trail, health/readiness, capacity stats, cleanup preview/run, and agent scheduling explanations. |
| Integrations | `/webhooks`, `/webhooks/{provider}`, `/pipeline/preview`, `/service/info`, `/help/content` | Auto-detected Gitee/GitHub webhooks plus installed providers, admin-only pipeline metadata preview, service version, and Help content. |

`POST /jobs`, `POST /jobs/{job_id}/reexecute` and `POST /jobs/bulk` accept an
`Idempotency-Key` header: a retry with the same key and payload returns the original answer
instead of creating a second job or build. Webhook deliveries are deduplicated server-side.

Routes that modify resources enforce ownership, sharing, or administrator permissions as
appropriate. Agent protocol endpoints use agent API keys where required. The UI and OpenAPI
schema are the authoritative references for each endpoint's exact payload and permission
requirements; the route list above is an orientation, not an exhaustive API specification.