Wuling DevOps

https://github.com/zixiao-labs/wuling-devops
Admin
Wuling DevOps is an all-in-one DevOps platform providing Git repository management, CI/CD pipelines...
Tokens:59,830
Snippets:333
Trust Score:6.8
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Windows runner.env configuration

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/runners/runner-clients/README.md

Configuration file for Windows static machine installation. Write this to C:\ProgramData\wuling-runner\runner.env after installing the setup.exe and minting a registration token.

```plaintext
WULING_RUNNER_SERVER_URL=https://wuling.example.com
WULING_RUNNER_REGISTRATION_TOKEN=wlreg_...
```

--------------------------------

### Deploy wuling binaries to non-NixOS host with systemd

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/deploy/production/README.md

Builds the wuling-api and wuling-migrate binaries with Nix, copies them to a remote host, and installs the provided systemd unit. The unit reads /etc/wuling/wuling.env, so copy env.example there and fill it in.

```bash
# 用 Nix 构出二进制（任意有 nix 的机器）
nix build .#wuling-api
nix build .#wuling-migrate

# 拷过去
scp result-*/bin/wuling-* user@host:/usr/local/bin/

# 用我们的 systemd unit
sudo cp deploy/production/systemd/wuling-api.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now wuling-api
```

--------------------------------

### First startup with docker-compose.prod.yml

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/deploy/production/README.md

First startup sequence for Docker Compose: create persistent volumes, start services, run database migration, and verify health. Requires ports 80/443 reachable for Caddy to obtain Let's Encrypt certificates via HTTP-01.

```bash
# 1. 建两个持久卷（compose 会自动创建，但显式创建可以指定挂载点）
docker volume create wuling-pg
docker volume create wuling-repos
docker volume create wuling-caddy-data

# 2. 启动
docker compose -f docker-compose.prod.yml up -d

# 3. 初始化数据库
docker compose -f docker-compose.prod.yml exec api wuling-migrate

# 4. 测一下
curl -sf https://${WULING_DOMAIN:-localhost}/healthz
```

--------------------------------

### Start Artifact Service locally

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/docs/artifacts.md

Command to run the wuling-artifacts service locally with specific environment variables for token, provider, and storage directory.

```bash
WULING_ARTIFACTS_INTERNAL_TOKEN=dev-token \
WULING_ARTIFACTS_STORAGE_PROVIDER=local \
WULING_ARTIFACTS_LOCAL_DIR=./var/artifacts \
go run ./cmd/wuling-artifacts
```

--------------------------------

### Deploy Kubernetes manifests with kubectl apply -k

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/deploy/production/README.md

Deploy the Kubernetes manifests in the k8s/ directory. First copy the secret example and replace jwt-secret and pg-password with strong random values, then update the ingress domain, apply with kubectl apply -k, and run the migration command.

```bash
# 1. 改 secret
cp k8s/secret.example.yaml k8s/secret.yaml
# 把 jwt-secret / pg-password 改成强随机值

# 2. 改 ingress 里的域名

# 3. 起
kubectl apply -k deploy/production/k8s/

# 4. 跑 migrate
kubectl -n wuling exec deploy/wuling-api -- wuling-migrate
```

--------------------------------

### Prepare .env from env.example

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/deploy/production/README.md

Prepares the production environment by copying env.example to .env and editing required variables. At minimum, change WULING_JWT_SECRET and WULING_DOMAIN. Do not commit the real .env file.

```bash
cd deploy/production
cp env.example .env
# 用编辑器打开 .env，至少改 WULING_JWT_SECRET / WULING_DOMAIN
```

--------------------------------

### Fully open demo deployment env vars

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/docs/auth.md

Recommended environment variables for a fully open teaching or demo instance. Approval is disabled and OAuth is optional. Do not use this configuration in production.

```bash
WULING_AUTH_REQUIRE_APPROVAL=false
# OAuth 可选
```

--------------------------------

### PATCH /api/v1/runner/jobs/{id}/steps/{number}

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/docs/pipelines.md

Reports a step-level status change (start, end, or conclusion).

```APIDOC
## PATCH /api/v1/runner/jobs/{id}/steps/{number}

### Description
Reports a step-level status change (start, end, or conclusion).

### Method
PATCH

### Endpoint
/api/v1/runner/jobs/{id}/steps/{number}

### Parameters
#### Path Parameters
- **id** (string) - Required - The job ID.
- **number** (integer) - Required - The step number.

#### Request Body
- **status** (string) - Required - The new step status (e.g., "started", "completed", "failed").

### Request Example
{
  "status": "completed"
}

### Response
#### Success Response (200)
- **status** (string) - "ok"

#### Response Example
{
  "status": "ok"
}

### Notes
- Authentication: Bearer token with the runner token.
```

--------------------------------

### GET /healthz

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/docs/artifacts.md

Health check endpoint for the artifact service. It verifies that the service is running and that the configured storage bucket is accessible.

```APIDOC
## GET /healthz

### Description
Health check endpoint for the artifact service. It verifies that the service is running and that the configured storage bucket is accessible.

### Method
GET

### Endpoint
/healthz

### Response
#### Success Response (200)
- **status** (string) - Service health status.

#### Response Example
{
  "status": "ok"
}

```

--------------------------------

### Configure rust-toolchain.toml

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/frontend/src/help/content/pipelines/rust-xtask.md

定义 Rust 工具链版本、配置项及组件，供 actions/setup-rust 读取。

```toml
# rust-toolchain.toml
[toolchain]
channel = "1.85.0"
profile = "minimal"
components = ["clippy", "rustfmt"]
```

--------------------------------

### Reference Wuling flake in NixOS configuration

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/deploy/production/README.md

Adds the Wuling flake as an input and wires its default NixOS module into a host configuration. The example targets x86_64-linux and includes the local host.nix module.

```nix
# flake.nix（系统配置）
{
  inputs.wuling.url = "github:zixiao-labs/Wuling-DevOps";
  outputs = { self, nixpkgs, wuling, ... }: {
    nixosConfigurations.devops-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        wuling.nixosModules.default
        ./host.nix
      ];
    };
  };
}
```

--------------------------------

### 本地开发预览命令

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/docs/help-center.md

在 frontend 目录下运行开发服务器，修改内容后支持热重载。

```bash
cd frontend
npm run dev
# 打开 http://localhost:3000/help
```

--------------------------------

### PyPI private registry configuration and commands

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/docs/unified-supply-chain-security.md

Configure pip to use the Wuling private PyPI index and upload packages with twine. The pip.conf sets the extra-index-url with a token, and the commands upload and install packages.

```ini
# pip.conf / environment
[global]
extra-index-url = https://__token__:${WULING_PYPI_TOKEN}@{host}/registry/pypi/{org}/{project}/simple/
```

```bash
twine upload --repository-url "{base}/registry/pypi/{org}/{project}/" dist/*
pip install <pkg> --extra-index-url "https://__token__:…@…"
```

--------------------------------

### Use built-in actions with `actions/setup-node@v4` and `actions/cache@v4`

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/frontend/src/help/content/pipelines/quick-start.md

Use built-in GitHub Actions-style actions by referencing the full action name and version. `actions/setup-node@v4` accepts `cache` values `npm`, `pnpm`, or `yarn`; `actions/setup-rust` does not enable Rust caching despite its `cache` input. For sharing directories across elastic or isolated runners, use `actions/cache@v4`, which writes to the remote Artifact Service via the Wuling API.

```yaml
steps:
  - uses: actions/checkout@v4

  - uses: actions/setup-node@v4
    with:
      node-version: "22"
      cache: npm

  - run: npm ci && npm test

```

--------------------------------

### npm private registry configuration and commands

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/docs/unified-supply-chain-security.md

Configure npm to use the Wuling private registry for a given org and project. The .npmrc sets the registry scope and token, while the commands publish and install packages against that registry.

```ini
# ~/.npmrc 或项目 .npmrc
@{scope}:registry={base}/registry/npm/{org}/{project}/
{base}/registry/npm/{org}/{project}/:_authToken=${WULING_NPM_TOKEN}
always-auth=true
```

```bash
npm publish --registry "{base}/registry/npm/{org}/{project}/"
npm install @scope/pkg --registry "{base}/registry/npm/{org}/{project}/"
```

--------------------------------

### Build Nix flake outputs for wuling-api, wuling-migrate, and wuling-frontend

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/deploy/production/README.md

Builds the three flake outputs from the repository root: the wuling-api binary, the wuling-migrate tool, and the wuling-frontend static folder. The comments show the expected result paths.

```bash
nix build .#wuling-api          # → result/bin/wuling-api
nix build .#wuling-migrate      # → result/bin/wuling-migrate
nix build .#wuling-frontend     # → result/   (静态文件夹)
```

--------------------------------

### Matrix build with `strategy.matrix` for Node.js versions

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/frontend/src/help/content/pipelines/quick-start.md

Use `strategy.matrix` to run tests in parallel across multiple Node.js versions and platforms. The example defines a matrix with Node.js 20 and 22, then uses `${{ matrix.node }}` to set the `node-version` for `actions/setup-node@v4`.

```yaml
strategy:
  matrix:
    node: ["20", "22"]
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: ${{ matrix.node }}

```

--------------------------------

### Enable wuling service and PostgreSQL in host.nix

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/deploy/production/README.md

Enables the wuling service in host.nix with domain, HTTP/SSH addresses, a Unix-socket Postgres URL, and a JWT secret file path. Also enables PostgreSQL with a wuling database and user, and opens firewall ports 80, 443, and 2222.

```nix
{ ... }: {
  services.wuling = {
    enable = true;
    domain = "devops.example.com";
    httpAddr = ":8080";
    sshAddr = ":2222";

    # Postgres 推荐用同机的 services.postgresql 起，连串走 Unix socket
    databaseUrl = "postgres:///wuling?host=/run/postgresql";

    # 强烈建议把 JWT secret 用 sops/agenix 注入；这里只是示意
    jwtSecretFile = "/run/secrets/wuling-jwt";

    # 仓库与 SSH host key 的持久路径
    repoRoot = "/var/lib/wuling/repos";
    sshHostKeyFile = "/var/lib/wuling/ssh/host_ed25519";

    frontend.enable = true;     # 用 nginx 静态托管 dist/
    reverseProxy = "caddy";     # 'caddy' | 'nginx' | 'none'
  };

  services.postgresql = {
    enable = true;
    ensureDatabases = [ "wuling" ];
    ensureUsers = [ { name = "wuling"; ensureDBOwnership = true; } ];
  };

  # 防火墙
  networking.firewall.allowedTCPPorts = [ 80 443 2222 ];
}
```

--------------------------------

### PUT /api/v1/orgs/{org}/projects/{project}/repos/{repo}/github-link

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/docs/github-integration.md

Binds a GitHub repository to a Wuling project. Requires maintainer identity. The control plane automatically uses the GitHub App JWT to query the repository installation, so no `installation_id` is needed from the user.

```APIDOC
## [PUT] /api/v1/orgs/{org}/projects/{project}/repos/{repo}/github-link

### Description
Binds a GitHub repository to a Wuling project. Requires maintainer identity. The control plane automatically uses the GitHub App JWT to query the repository installation, so no `installation_id` is needed from the user.

### Method
PUT

### Endpoint
/api/v1/orgs/{org}/projects/{project}/repos/{repo}/github-link

### Parameters
#### Path Parameters
- **org** (string) - Required - Organization name.
- **project** (string) - Required - Project name.
- **repo** (string) - Required - Repository name.

#### Request Body
- **owner** (string) - Required - GitHub repository owner.
- **name** (string) - Required - GitHub repository name.

### Request Example
{
  "owner": "acme",
  "name": "app"
}

### Response
#### Success Response (200)
- **status** (string) - Indicates the binding was successful.

#### Response Example
{
  "status": "ok"
}

### Error Handling
- **400** - App not installed or not granted access to the repository. Response includes the public installation URL: `https://github.com/apps/wuling-devops/installations/new`.
```

--------------------------------

### 配置 xtask alias 的 .cargo/config.toml

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/docs/pipelines-rust-xtask.md

在 workspace 的 .cargo/config.toml 中定义 xtask alias，使 `cargo xtask ci` 可执行。推荐将自动化命令放入 xtask crate，并确保命令不依赖未声明的本机路径、交互式提示或长效凭据。

```toml
# .cargo/config.toml
[alias]
xtask = "run --package xtask --"
```

--------------------------------

### GET /v1/blobs/{key}

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/docs/artifacts.md

Internal Blob API to retrieve a blob. Requires an internal token. The key must follow the format `projects/{project_id}/packages/{package_id}/{version}` or `pipeline-cache/{org_id}/{project_id}/{repo_id}/{entry_id}.cache`. The service rejects empty segments, absolute paths, `..`, and the reserved `.metadata` segment.

```APIDOC
## GET /v1/blobs/{key}

### Description
Internal Blob API to retrieve a blob. Requires an internal token. The key must follow the format `projects/{project_id}/packages/{package_id}/{version}` or `pipeline-cache/{org_id}/{project_id}/{repo_id}/{entry_id}.cache`. The service rejects empty segments, absolute paths, `..`, and the reserved `.metadata` segment.

### Method
GET

### Endpoint
/v1/blobs/{key}

### Parameters
#### Path Parameters
- **key** (string) - Required - The blob key.

### Headers
- **Authorization** (string) - Required - Bearer token with the internal token.

### Response
#### Success Response (200)
- **body** (binary) - The blob content.

#### Response Example
(binary content)

```

--------------------------------

### 注册自托管 Runner 命令

Source: https://github.com/zixiao-labs/wuling-devops/blob/main/frontend/src/help/content/runners.md

在目标机器上执行此命令以注册 Runner。需要替换 <registration-token> 为实际令牌，并可根据需要调整 --name 和 --labels。

```bash
wuling-runner \
  --server-url https://your-host \
  --registration-token <registration-token> \
  --name my-runner \
  --labels linux,docker
```
Tokens:
Raw