Server

Server configuration for Crow CI.

Authentication

Forge Integration

Crow authenticates users via OAuth2 from a Git forge:

Forge	Environment Variable
Forgejo	CROW_FORGEJO=true
Gitea	CROW_GITEA=true
GitHub	CROW_GITHUB=true
GitLab	CROW_GITLAB=true
Bitbucket DC	CROW_BITBUCKET=true

There is no manual user registration - all users must authenticate via the forge.

Registration

Registration is closed by default (CROW_OPEN=false). When open, any forge user can register.

Caution

Restrict access using CROW_ORGS to limit registration to organization members:

CROW_ORGS=myorg

Admin Users

CROW_ADMIN=johnDoe,janeSmith

Admins can also be promoted via UI: Settings → Users → Edit User.

Database

Driver	Configuration
SQLite (default)	Data stored in /var/lib/crow/
PostgreSQL (≥11)	CROW_DATABASE_DRIVER=postgres
MySQL/MariaDB	CROW_DATABASE_DRIVER=mysql

PostgreSQL

CROW_DATABASE_DRIVER=postgres
CROW_DATABASE_DATASOURCE=postgres://user:pass@localhost:5432/crow?sslmode=disable

MySQL/MariaDB

CROW_DATABASE_DRIVER=mysql
CROW_DATABASE_DATASOURCE=user:pass@tcp(localhost:3306)/crow?parseTime=true

Note

Migrations run automatically on startup. Downgrading after a migration is not supported.

Encryption

Crow encrypts sensitive data at rest using Google Tink:

• Secrets
• Registry credentials
• User OAuth tokens
• Forge client secrets

Setup

CROW_ENCRYPTION_TINK_KEYSET_FILE=/path/to/keyset.json

Generate a keyset with Tinkey:

tinkey create-keyset --key-template AES256_GCM_SIV --out keyset.json --out-format json

Caution

Back up your keyset file. Without it, encrypted data cannot be recovered.

Key Rotation

tinkey rotate-keyset --in keyset.json --out keyset.json --key-template AES256_GCM_SIV

Crow re-encrypts data with the new primary key on restart.

Disabling Encryption

CROW_ENCRYPTION_DISABLE=true

This decrypts all data back to plaintext.

Backends

The backend determines where pipelines execute.

Backend	Use Case
docker	Default, containers on agent host
kubernetes	Pods in K8s cluster
local	Direct execution (development only)

Docker

Each step runs in a separate container on the agent.

Private Registries

Use CROW_DOCKER_CONFIG to pass Docker credential helpers, or configure credentials in the Crow UI.

Backend Options

steps:
  - name: test
    image: alpine
    backend_options:
      docker:
        user: 65534:65534

Housekeeping

Crow doesn’t auto-clean Docker images. Add to your maintenance routine:

# Remove dangling images
docker image prune -f

# Remove orphaned Crow volumes
docker volume rm $(docker volume ls --filter name=^crow_* --filter dangling=true -q)

Kubernetes

Each step runs in a separate Pod. A temporary PVC transfers files between steps.

Private Registries

CROW_BACKEND_K8S_PULL_SECRET_NAMES=my-registry-secret

The secret must be type kubernetes.io/dockerconfigjson in the namespace set by CROW_BACKEND_K8S_NAMESPACE.

Backend Options

steps:
  - name: build
    image: alpine
    backend_options:
      kubernetes:
        resources:
          requests:
            memory: 200Mi
            cpu: 100m
          limits:
            memory: 400Mi
            cpu: 1000m

Additional supported options: nodeSelector, tolerations, securityContext, annotations, labels, runtimeClassName.

Note

Set CROW_BACKEND_K8S_POD_ANNOTATIONS_ALLOW_FROM_STEP=true to allow annotations from pipeline config.

Local

Danger

Executes pipelines without isolation. Use only for development with trusted code.

CROW_BACKEND=local

The image field specifies the shell (e.g., bash, fish). Plugins work as executables in $PATH.

Metrics

Crow exposes Prometheus metrics at /metrics.

Configuration

CROW_PROMETHEUS_AUTH_TOKEN=your-token

Prometheus Scrape Config

scrape_configs:
  - job_name: crow
    bearer_token: your-token
    static_configs:
      - targets: ['crow.example.com']

Available Metrics

Metric	Description
crow_pipeline_count	Pipeline count by repo/branch/status
crow_pipeline_time	Build time
crow_pipeline_total_count	Total pipelines
crow_pending_steps	Pending steps
crow_running_steps	Running steps
crow_repo_count	Total repos
crow_user_count	Total users
crow_worker_count	Connected agents

SSL/TLS

Tip

Using a reverse proxy is recommended over direct TLS termination.

CROW_SERVER_CERT=/path/to/server.crt
CROW_SERVER_KEY=/path/to/server.key

Expose port 443 and mount certificates when using containers.

Logging

Variable	Default	Description
CROW_LOG_LEVEL	info	Log level
CROW_LOG_FILE	stderr	Log output destination
CROW_LOG_STORE	database	Pipeline log storage
CROW_LOG_STORE_FILE_PATH	-	File path for pipeline logs

Log Rotation (Alpine Images)

Alpine images auto-rotate logs when CROW_LOG_FILE is set to a file path:

Variable	Default	Description
CROW_LOGROTATE_SCHEDULE	0 0 * * *	Cron schedule
CROW_LOGROTATE_RETAIN_DAYS	7	Days to keep

External Config API

A server-side hook that lets Crow admins dynamically generate or modify pipeline configurations before execution.

Note

This is an admin-level feature configured on the Crow server. Individual repository users cannot enable or configure it — it applies globally to all pipelines.

CROW_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig

Use Cases

• Centralized pipeline templates — inject standard steps (security scanning, linting) across all repos
• Dynamic configuration — generate pipelines based on changed files or branch patterns
• Policy enforcement — validate or modify pipelines to meet organizational standards
• Monorepo support — generate targeted pipelines based on which packages changed

How It Works

sequenceDiagram
    participant Forge as Git Forge
    participant Crow as Crow Server
    participant Config as Config Service
    participant Agent as Crow Agent

    Forge->>Crow: Webhook (push, PR, etc.)
    Crow->>Config: POST /ciconfig
    Note right of Config: Evaluate branch,<br/>changed files, etc.
    alt Return custom config
        Config->>Crow: HTTP 200 + configs
    else Use existing
        Config->>Crow: HTTP 204
    end
    Crow->>Agent: Execute pipeline

1. Before each pipeline run, Crow sends a POST request to the endpoint with repo and pipeline metadata

2. The config service processes the request and can make dynamic decisions based on branch, changed files, event type, etc.

3. The service returns new configs (HTTP 200) or signals “use existing” (HTTP 204)

Requests are signed with ed25519. Get the public key for verification from /api/signature/public-key.

Deployment

The config service is a separate application you deploy and maintain. It can run anywhere accessible to the Crow server:

Deployment Option	Notes
Kubernetes pod	Same cluster as Crow, use internal service URL
Standalone VM	Any HTTP-accessible server
Serverless	AWS Lambda, Cloud Functions, etc.
Sidecar	Container alongside Crow server

Setup:

1. Deploy your config service (see example below)
2. Ensure it’s reachable from the Crow server
3. Set CROW_CONFIG_SERVICE_ENDPOINT to the service URL
4. Restart Crow server

# Example: Crow server configuration
CROW_CONFIG_SERVICE_ENDPOINT=http://config-service.crow.svc:8080

Request Format

{
  "repo": {
    "id": 100,
    "name": "my-repo",
    "owner": "my-org",
    "private": true,
    "default_branch": "main"
  },
  "pipeline": {
    "event": "push",
    "branch": "main",
    "commit": "abc123...",
    "author": "user",
    "message": "commit message",
    "changed_files": ["src/main.go", "pkg/api/handler.go"]
  },
  "netrc": {
    "machine": "github.com",
    "login": "x-token",
    "password": "ghp_..."
  }
}

Response Format

Return HTTP 200 with new configs:

{
  "configs": [
    {
      "name": ".crow/build.yaml",
      "data": "steps:\n  - name: build\n    image: golang:1.22\n    commands:\n      - go build ./..."
    }
  ]
}

Return HTTP 204 (no body) to use the existing repository configs.

Example: Dynamic Config Service

A simple Go service that injects security scanning for main branch pushes:

package main

import (
    "encoding/json"
    "net/http"
    "strings"
)

type Request struct {
    Repo     struct{ Name string } `json:"repo"`
    Pipeline struct {
        Event        string   `json:"event"`
        Branch       string   `json:"branch"`
        ChangedFiles []string `json:"changed_files"`
    } `json:"pipeline"`
}

type Response struct {
    Configs []struct {
        Name string `json:"name"`
        Data string `json:"data"`
    } `json:"configs"`
}

func handler(w http.ResponseWriter, r *http.Request) {
    var req Request
    json.NewDecoder(r.Body).Decode(&req)

    // Only modify main branch pushes
    if req.Pipeline.Branch != "main" || req.Pipeline.Event != "push" {
        w.WriteHeader(http.StatusNoContent) // Use existing config
        return
    }

    // Inject security scanning step
    config := `steps:
  - name: security-scan
    image: aquasec/trivy
    commands:
      - trivy fs --severity HIGH,CRITICAL .
  - name: build
    image: golang:1.22
    commands:
      - go build ./...
`
    resp := Response{
        Configs: []struct {
            Name string `json:"name"`
            Data string `json:"data"`
        }{{Name: ".crow/build.yaml", Data: config}},
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(resp)
}

func main() {
    http.HandleFunc("/", handler)
    http.ListenAndServe(":8080", nil)
}

Caution

The config service receives repository credentials (netrc) and can execute arbitrary code via modified pipelines. Only deploy trusted, secured services.

High Availability

Caution

Experimental feature.

Run multiple server instances with PostgreSQL or MySQL for HA. The database coordinates queue processing and cron execution.

CROW_ENABLE_HA=true

Variable	Default	Description
CROW_QUEUE_LOCK_TTL	30s	Queue lock timeout
CROW_CRON_LOCK_TTL	90s	Cron lock timeout

With Helm, set server.replicaCount > 1.

Maintenance

Built-in maintenance jobs accessible via Settings → Maintenance.

Vacuum

Reclaims database space after log deletion. Essential for SQLite.

Kubernetes Cleanup

Removes orphaned resources (PVCs, secrets, services) older than 7 days.

CROW_MAINTENANCE_KUBERNETES_CLEANUP_AGE=168h