### Quick Start Commands

Source: https://crowci.dev/v5-11/development

Commands to clone the repository, install dependencies, run tests, and start local development.

```bash
# Clone the repository
git clone https://codefloe.com/crowci/crow.git
cd crow

# Install Go dependencies
just install-dev-deps

# Run tests
just test

# Start local development (requires .env file)
# Use VSCode "Crow CI" launch configuration

```

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

### Install Frontend Dependencies

Source: https://crowci.dev/v5-11/development/setup

Navigates to the web directory and installs frontend dependencies using Bun.

```bash
cd web
bun install
```

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

### First Pipeline Configuration

Source: https://crowci.dev/v5-11/quickstart

Example of a .crow/build.yaml file for the first pipeline.

```yaml
steps:
  - name: test
    image: alpine
    commands:
      - echo "Hello from Crow CI!"
      - echo "${CI_REPO}"
```

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

### Verify Installation

Source: https://crowci.dev/v5-11/development/setup

Verifies the installation of Go, Bun, and Just, and runs linters.

```bash
# Check Go
go version

# Check Bun
bun --version

# Check Just
just --version

# Run linters
just lint
```

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

### Full example

Source: https://crowci.dev/v5-11/usage/services

Full example

```yaml
services:
  - name: database
    image: mysql
    environment:
      - MYSQL_DATABASE=test
      - MYSQL_ROOT_PASSWORD=example
steps:
  - name: get-version
    image: ubuntu
    commands:
      - ( apt update && apt dist-upgrade -y && apt install -y mysql-client 2>&1 )> /dev/null
      - sleep 20s # need to wait for mysql-server init
      - echo 'SHOW VARIABLES LIKE "version"' | mysql -u root -h database test -p example
```

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

### Install Go Dependencies

Source: https://crowci.dev/v5-11/development/setup

Installs Go development dependencies using the 'just' task runner.

```bash
just install-dev-deps
```

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

### Dual-Provider Setup Example

Source: https://crowci.dev/v5-11/configuration/autoscaler

Placeholder for an example demonstrating a dual-provider setup with multiple autoscalers.

```shell

```

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

### Settings Configuration Example

Source: https://crowci.dev/v5-11/plugins/creating-plugins

Example of how a user configures plugin settings in a pipeline.

```yaml
steps:
  - name: notify
    image: my-plugin
    settings:
      server: https://api.example.com
      message: Hello World
      retry_count: 3
```

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

### Local Server Configuration Override

Source: https://crowci.dev/v5-11/installation/binary

Example of how to configure the plist for a local server connection without TLS.

```xml
<key>CROW_SERVER</key>
<string>your-server-ip:9000</string>
```

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

### Example: Multi-Forge Setup

Source: https://crowci.dev/v5-11/configuration/env-vars/forge

Demonstrates a multi-forge setup with configurations for Codeberg, GitHub, and an internal forge.

```shell
# Define forges
CROW_FORGES=codeberg,github,internal

# Codeberg (Forgejo) - icon auto-detected from URL
CROW_FORGE_CODEBERG_TYPE=forgejo
CROW_FORGE_CODEBERG_URL=https://codeberg.org
CROW_FORGE_CODEBERG_CLIENT=your-client-id
CROW_FORGE_CODEBERG_SECRET=your-client-secret

# GitHub - uses default GitHub icon
CROW_FORGE_GITHUB_TYPE=github
CROW_FORGE_GITHUB_CLIENT=your-github-client-id
CROW_FORGE_GITHUB_SECRET=your-github-client-secret

# Internal Forgejo instance - custom icon
CROW_FORGE_INTERNAL_TYPE=forgejo
CROW_FORGE_INTERNAL_URL=https://git.internal.company.com
CROW_FORGE_INTERNAL_CLIENT=your-internal-client-id
CROW_FORGE_INTERNAL_SECRET=your-internal-client-secret
CROW_FORGE_INTERNAL_ICON=https://internal.company.com/logo.svg

```

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

### Setup Pre-commit Hooks

Source: https://crowci.dev/v5-11/development/setup

Installs pre-commit hooks for Git.

```bash
pre-commit install
```

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

### Tmpfs Mount Example

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Example of using tmpfs mounts for services, including a PostgreSQL database.

```yaml
steps:
  - name: test
    image: golang
    commands:
      - go test ./...

services:
  - name: database
    image: postgres:18
    tmpfs:
      - /var/lib/postgresql
```

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

### macOS Launch Daemon Plist Configuration

Source: https://crowci.dev/v5-11/installation/binary

Example plist file content for running the Crow CI agent as a system service using launchd.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>crowci.agent</string>

    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/crow-agent</string>
    </array>

    <key>EnvironmentVariables</key>
    <dict>
        <key>CROW_SERVER</key>
        <string>your-server.com</string>
        <key>CROW_GRPC_ADDR</key>
        <string>grpc.your-server.com:443</string>
        <key>CROW_GRPC_SECURE</key>
        <string>true</string>
        <key>CROW_AGENT_SECRET</key>
        <string>your-secret-token</string>
        <key>CROW_BACKEND</key>
        <string>local</string>
        <key>CROW_BACKEND_LOCAL_SANDBOX_LEVEL</key>
        <string>standard</string>
        <key>CROW_AGENT_CONFIG_FILE</key>
        <string>/usr/local/var/crow-agent/config.yml</string>
    </dict>

    <key>StandardOutPath</key>
    <string>/usr/local/var/log/crow-agent.log</string>

    <key>StandardErrorPath</key>
    <string>/usr/local/var/log/crow-agent-error.log</string>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>WorkingDirectory</key>
    <string>/usr/local/var/crow-agent</string>
</dict>
</plist>
```

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

### Runs On Example

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Example of configuring a workflow to run on specific conditions.

```yaml
runs_on: [success, failure]
```

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

### Quick Example

Source: https://crowci.dev/v5-11/plugins

A quick example demonstrating how to use a plugin in a pipeline configuration. The `settings` key passes configuration to the plugin, which are then exposed as `PLUGIN_` environment variables.

```yaml
steps:
  - name: deploy
    image: codefloe.com/crow-plugins/docker-buildx
    settings:
      repo: myorg/myapp
      dockerfile: Dockerfile
      tags: latest
```

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

### Install the chart

Source: https://crowci.dev/v5-11/installation/helm

Installs the Crow CI chart from the added repository.

```bash
helm install crow crowci/crow
```

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

### Build Workflow Example

Source: https://crowci.dev/v5-11/usage/pipelines

An example of a build workflow that can be manually triggered.

```yaml
# .crow/build.yaml
when:
  - event: manual

steps:
  - name: build
    image: golang
    commands:
      - go build

```

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

### Using Integration by Name Example

Source: https://crowci.dev/v5-11/usage/integrations

Example demonstrating how to reference an integration by its name instead of its ID for better readability.

```yaml
steps:
  - name: deploy
    image: alpine
    environment:
      API_KEY:
        from_secret:
          integration: "vault-prod"   # Use integration name instead of ID
          path: 'crow/myapp'
          key: 'api_key'
```

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

### Privileged Plugin Image Matching - Exact Example

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Example of setting environment variables for privileged plugin image matching using exact match.

```bash
export CROW_PLUGINS_PRIVILEGED="codefloe.com/crow-plugins/docker-buildx:1.0.0"
export CROW_PLUGINS_PRIVILEGED_MATCH_TYPE=exact
```

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

### Deploy Workflow Example

Source: https://crowci.dev/v5-11/usage/pipelines

An example of a deploy workflow that depends on the build workflow and can be manually triggered.

```yaml
# .crow/deploy.yaml
when:
  - event: manual

depends_on:
  - build

steps:
  - name: deploy
    image: alpine
    commands:
      - ./deploy.sh

```

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

### macOS Binary Installation

Source: https://crowci.dev/v5-11/installation/binary

Steps to download, extract, and install the Crow CI agent binary on macOS.

```bash
export VERSION=4.3.0
export ARCH=arm64
curl -LO https://codefloe.com/crowci/crow/releases/download/v$VERSION/crow-agent_darwin_$ARCH.tar.gz

# Extract the archive
tar -xzf crow-agent_darwin_*.tar.gz

# Move to system path
sudo mv crow-agent /usr/local/bin/
sudo chmod +x /usr/local/bin/crow-agent

# Verify installation
crow-agent --version
```

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

### Enable Rootless Podman Socket Service

Source: https://crowci.dev/v5-11/configuration/env-vars/backend-podman

Command to enable and start the user systemd service for the Podman socket, necessary for rootless Podman installations.

```bash
systemctl --user enable --now podman.socket
```

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

### docker-compose.yml

Source: https://crowci.dev/v5-11/quickstart

A docker-compose.yml file to set up Crow CI server and agent.

```yaml
services:
  server:
    image: codefloe.com/crowci/crow-server:<version>
    ports:
      - "8000:8000"
      - "9000:9000"
    volumes:
      - crow-data:/var/lib/crow
    environment:
      - CROW_OPEN=true
      - CROW_HOST=http://localhost:8000
      - CROW_AGENT_SECRET=your-agent-secret
      - CROW_FORGEJO=true
      - CROW_FORGEJO_URL=https://codeberg.org
      - CROW_FORGEJO_CLIENT=your-oauth-client-id
      - CROW_FORGEJO_SECRET=your-oauth-client-secret

  agent:
    image: codefloe.com/crowci/crow-agent:<version>
    depends_on:
      - server
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - CROW_SERVER=server:9000
      - CROW_AGENT_SECRET=your-agent-secret

volumes:
  crow-data:
```

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

### Basic Plugin Usage

Source: https://crowci.dev/v5-11/plugins/using-plugins

Example of defining a plugin as a step with an image and settings.

```yaml
steps:
  - name: notify
    image: codeberg.org/woodpecker-plugins/mastodon-post
    settings:
      server: https://fosstodon.org
      access_token:
        from_secret: mastodon_token
      message: "Build completed successfully!"
```

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

### Privileged Plugin Image Matching - Semver Example

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Example of setting environment variables for privileged plugin image matching using semver.

```bash
export CROW_PLUGINS_PRIVILEGED="codefloe.com/crow-plugins/docker-buildx:1,plugins/gcr:7.2"
export CROW_PLUGINS_PRIVILEGED_MATCH_TYPE=semver
```

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

### Docker Compose Example for Autoscaler

Source: https://crowci.dev/v5-11/configuration/autoscaler

A complete docker-compose.yaml example demonstrating the configuration of the Crow CI Autoscaler, including server connection, scaling limits, gRPC settings, timeouts, and cloud provider specifics (Hetzner example).

```yaml
# docker-compose.yaml
services:
  crow-autoscaler:
    image: codefloe.com/crowci/crow-autoscaler:<version>
    restart: always
    depends_on:
      - crow-server
    environment:
      # Server connection
      - CROW_SERVER=crow-server:9000
      - CROW_TOKEN=${CROW_TOKEN} # Admin API token
      - CROW_AUTOSCALER_TOKEN=${CROW_AUTOSCALER_TOKEN}

      # Scaling limits
      - CROW_MIN_AGENTS=0
      - CROW_MAX_AGENTS=2
      - CROW_WORKFLOWS_PER_AGENT=5

      # gRPC (for remote agents)
      - CROW_GRPC_ADDR=grpc.crow.example.com
      - CROW_GRPC_SECURE=true

      # Timeouts
      - CROW_AGENT_IDLE_TIMEOUT=10m
      - CROW_AGENT_SERVER_CONNECTION_TIMEOUT=10m

      # Cloud provider (Hetzner example)
      - CROW_PROVIDER=hetznercloud
      - CROW_HETZNERCLOUD_API_TOKEN=${HETZNER_TOKEN}
      - CROW_HETZNERCLOUD_LOCATION=fsn1
      - CROW_HETZNERCLOUD_SERVER_TYPE=cax41
      - CROW_HETZNERCLOUD_IMAGE=ubuntu-24.04
      - CROW_HETZNERCLOUD_NETWORKS=my-network
      - CROW_HETZNERCLOUD_SSH_KEYS=my-key
      - CROW_HETZNERCLOUD_FIREWALLS=my-firewall

      # Agent image (optional — auto-detected from server version if omitted)
      # - CROW_AGENT_IMAGE=codefloe.com/crowci/crow-agent:v5.3.2

      # Optional: agent environment
      - CROW_AGENT_ENV=CROW_LOG_LEVEL=debug,CROW_HEALTHCHECK=false
```

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

### Matrix Pipeline Example

Source: https://crowci.dev/v5-11/usage/pipelines

An example of a matrix pipeline that runs on multiple platforms.

```yaml
matrix:
  platform:
    - linux/amd64
    - linux/arm64

steps:
  - name: test
    image: <image>
    commands:
      - echo "Running on ${platform}"

  - name: test-arm
    image: <image>
    commands:
      - echo "Running on ${platform}"
    when:
      platform: linux/arm*

```

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

### Complex Settings Example

Source: https://crowci.dev/v5-11/plugins/creating-plugins

Demonstrates how complex settings like arrays and objects are handled and JSON-serialized.

```yaml
settings:
  targets:
    - production
    - staging
  config:
    retries: 3
    timeout: 30
```

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

### Matrix workflow example with 'include'

Source: https://crowci.dev/v5-11/usage/pipelines

Example of a matrix workflow using 'include' for specific variable combinations.

```yaml
matrix:
  include:
    - GO_VERSION: 1.4
      REDIS_VERSION: 2.8
    - GO_VERSION: 1.5
      REDIS_VERSION: 2.8

```

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

### Privileged Plugin Image Matching - Regex Example

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Example of setting environment variables for privileged plugin image matching using regex.

```bash
export CROW_PLUGINS_PRIVILEGED="codefloe.com/crow-plugins/docker-buildx:1\..*"
export CROW_PLUGINS_PRIVILEGED_MATCH_TYPE=regex
```

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

### Privileged Plugin Image Matching - Semver Range Example

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Example of setting environment variables for privileged plugin image matching using semver-range.

```bash
export CROW_PLUGINS_PRIVILEGED="codefloe.com/crow-plugins/docker-buildx:>=1.0.0,<2.0.0"
export CROW_PLUGINS_PRIVILEGED_MATCH_TYPE=semver-range
```

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

### Steps with Commands

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Example of defining steps with a list of commands to be executed serially.

```yaml
steps:
  - name: backend
    image: <image>
    commands:
      - go build
      - go test
```

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

### Skip Clone Example

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Example of skipping the automatic clone step in a workflow.

```yaml
skip_clone: true
```

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

### Install using OCI directly

Source: https://crowci.dev/v5-11/installation/helm

Installs the Crow CI chart directly using OCI.

```bash
helm install crow oci://codefloe.com/crowci/crow
```

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

### Matrix workflow example with multiple variables

Source: https://crowci.dev/v5-11/usage/pipelines

Example of a matrix workflow defining multiple variables.

```yaml
matrix:
  GO_VERSION:
    - 1.4
    - 1.3
  REDIS_VERSION:
    - 2.6
    - 2.8
    - 3.0

```

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

### Integration Testing Pipeline Configuration

Source: https://crowci.dev/v5-11/plugins/creating-plugins

Example of a test pipeline configuration using a plugin.

```yaml
steps:
  - name: test-plugin
    image: my-plugin:dev
    settings:
      server: https://api.example.com
      token:
        from_secret: test_token
      message: "Test message"

```

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

### Static Agent Configuration Example

Source: https://crowci.dev/v5-11/configuration/autoscaler

Example configuration for a static agent, setting its labels.

```shell
CROW_AGENT_LABELS=tier=standard
```

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

### Platform: Wildcard Platforms

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Example of executing a step for specific platforms using wildcards.

```yaml
when:
  - platform: ['linux/*', 'windows/amd64']
```

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

### Platform: Specific Platform

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Example of executing a step for a specific platform (linux/amd64).

```yaml
when:
  - platform: linux/amd64
```

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

### Multi-Forge Support Configuration Example

Source: https://crowci.dev/v5-11/configuration/server

Example configuration for connecting to multiple Git forges simultaneously, with specific settings for Codeberg and GitHub.

```shell
CROW_FORGES=codeberg,github # arbitrary names

# Codeberg
CROW_FORGE_CODEBERG_TYPE=forgejo
CROW_FORGE_CODEBERG_URL=https://codeberg.org
CROW_FORGE_CODEBERG_CLIENT=your-client-id
CROW_FORGE_CODEBERG_SECRET=your-client-secret

# GitHub
CROW_FORGE_GITHUB_TYPE=github
CROW_FORGE_GITHUB_CLIENT=your-github-client-id
CROW_FORGE_GITHUB_SECRET=your-github-client-secret
```

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

### Repo: Filter by Repository

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Example of filtering by a specific repository.

```yaml
when:
  - repo: test/test
```

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

### Step with Environment Variables

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Example of passing arbitrary environment variables to individual steps.

```yaml
steps:
  - name: backend
    image: <image>
    environment:
      XY: true
    commands: |
      go build
      go test
```

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

### Workspace Configuration

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Example of configuring the workspace base and path for shared volumes and working directories.

```yaml
workspace:
  base: /go
  path: src/github.com/octocat/hello-world
```

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

### Plugin Dependencies

Source: https://crowci.dev/v5-11/plugins/using-plugins

Example of controlling plugin execution order using `depends_on`.

```yaml
steps:
  - name: test
    image: golang
    commands:
      - go test ./...

  - name: deploy
    image: codefloe.com/crow-plugins/docker-buildx
    settings:
      repo: myorg/myapp
    depends_on: [test]
```

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

### Conditional Plugin Execution

Source: https://crowci.dev/v5-11/plugins/using-plugins

Example of using `when` conditions to control when plugins run.

```yaml
steps:
  - name: deploy-prod
    image: codefloe.com/crow-plugins/docker-buildx
    settings:
      repo: myorg/myapp
      tags: latest
    when:
      branch: main
      event: push
```

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

### Event: Multiple Events

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Example of executing a step for multiple specified events.

```yaml
when:
  - event: [push, tag, deployment, manual]
  # alternative syntax
  # - event:
  #     - push
  #     - tag
  #     - deployment
  #     - manual
```

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

### Correct Plugin Configuration (Settings)

Source: https://crowci.dev/v5-11/plugins/using-plugins

Demonstrates the correct way to pass variables to plugins using `settings:`.

```yaml
# ✅ Correct - use settings
steps:
  - name: deploy
    image: some-plugin
    settings:
      my_var: value
```

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

### Image Usage in Steps and Services

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Examples showing the usage of the `image` attribute for steps and services.

```yaml
steps:
  - name: build
    image: <image>

services:
  - name: database
    image: mysql
```

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

### Jsonnet Build Workflow

Source: https://crowci.dev/v5-11/usage/jsonnet

Example of a Jsonnet file importing a library to define build steps.

```jsonnet
local lib = import "lib.libsonnet";

{
  steps: [
    lib.step("build", ["go build ./..."]),
  ],
}
```

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

### Building Binaries

Source: https://crowci.dev/v5-11/development/building

Commands to build server, agent, CLI, and UI binaries.

```bash
# Build server
just build-server

# Build agent
just build-agent

# Build CLI
just build-cli

# Build UI
just build-ui
```

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

### Ref: Tag Prefix Filter

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Example of filtering tags that start with 'v' using the 'ref' filter.

```yaml
when:
  - event: tag
    ref: refs/tags/v*
```

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

### Security Best Practice: Environment vs Settings

Source: https://crowci.dev/v5-11/plugins/creating-plugins

Illustrates the incorrect use of `environment:` and the correct approach using `settings:` for security.

```yaml
# ❌ Not allowed
steps:
  - name: deploy
    image: my-plugin
    environment:
      SECRET_KEY: value

# ✅ Required approach
steps:
  - name: deploy
    image: my-plugin
    settings:
      secret_key: value
```

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

### Per-step memory limit configuration

Source: https://crowci.dev/v5-11/troubleshooting

Example of setting a per-step memory limit in the pipeline YAML.

```yaml
steps:
  - name: build
    image: golang:1.23
    commands:
      - go build ./...
    backend_options:
      docker:
        mem_limit: '4g' # or remove to drop the limit for this step
```

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

### Step with Failure Handling

Source: https://crowci.dev/v5-11/usage/workflow-syntax

Example of configuring a step to ignore failures, allowing the workflow to continue.

```yaml
steps:
  - name: backend
    image: <image>
    commands:
      - go build
      - go test
    failure: ignore
```

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

### Plugin Script Example

Source: https://crowci.dev/v5-11/plugins/creating-plugins

A simple bash script demonstrating how to read settings from environment variables and use them to make an API call.

```bash
#!/bin/bash
# plugin.sh

# Read settings from environment
echo "Server: ${PLUGIN_SERVER}"
echo "Message: ${PLUGIN_MESSAGE}"

# Plugin logic here
curl -X POST "${PLUGIN_SERVER}/api/notify" \
  -H "Authorization: Bearer ${PLUGIN_TOKEN}" \
  -d "message=${PLUGIN_MESSAGE}"
```

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

### Simple Settings Conversion

Source: https://crowci.dev/v5-11/plugins/using-plugins

Demonstrates how boolean, numeric, and string settings are converted to environment variables.

```yaml
settings:
  enabled: true      # → PLUGIN_ENABLED="true"
  count: 5           # → PLUGIN_COUNT="5"
  message: hello     # → PLUGIN_MESSAGE="hello"
```

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

### Workflow dependency example

Source: https://crowci.dev/v5-11/usage/pipelines

Example of using 'depends_on' for workflow dependency resolution.

```yaml
steps:
  - name: deploy
    image: <image>:<tag>
    commands:
      - some command

# these are names of other workflows
depends_on:
  - lint
  - build
  - test

```

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

### Input Validation Example

Source: https://crowci.dev/v5-11/plugins/creating-plugins

Bash script showing how to validate required settings, provide defaults for optional settings, and validate URL format.

```bash
#!/bin/bash
set -euo pipefail

# Required settings
: "${PLUGIN_SERVER:?SERVER setting is required}"
: "${PLUGIN_TOKEN:?TOKEN setting is required}"

# Optional with defaults
PLUGIN_TIMEOUT="${PLUGIN_TIMEOUT:-30}"
PLUGIN_RETRIES="${PLUGIN_RETRIES:-3}"

# Validate format
if [[ ! "${PLUGIN_SERVER}" =~ ^https?:// ]]; then
  echo "Error: SERVER must be a valid URL"
  exit 1
fi
```

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

### Install the Collection

Source: https://crowci.dev/v5-11/installation/ansible

Install the devxy.cicd Ansible collection using ansible-galaxy.

```bash
ansible-galaxy collection install devxy.cicd
```

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

### Python Plugin Example

Source: https://crowci.dev/v5-11/plugins/creating-plugins

A basic Python plugin demonstrating how to access environment variables and handle JSON settings.

```python
#!/usr/bin/env python3
import os
import sys
import json

def main():
    server = os.environ.get('PLUGIN_SERVER')
    token = os.environ.get('PLUGIN_TOKEN')

    if not server or not token:
        print("Error: SERVER and TOKEN are required")
        sys.exit(1)

    # Handle complex settings (JSON)
    targets_json = os.environ.get('PLUGIN_TARGETS', '[]')
    targets = json.loads(targets_json)

    # Plugin logic here
    print(f"Deploying to {server}")
    for target in targets:
        print(f"  - {target}")

if __name__ == '__main__':
    main()

```

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

### Basic event trigger example

Source: https://crowci.dev/v5-11/usage/pipelines

Example of a basic event trigger for a 'push' event.

```yaml
when:
  event: push

```

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

### Server Configuration for Privileged Plugins

Source: https://crowci.dev/v5-11/plugins/using-plugins

Example of server administrator configuration to allow privileged plugins.

```shell
export CROW_PLUGINS_PRIVILEGED="codefloe.com/crow-plugins/docker-buildx:1"
export CROW_PLUGINS_PRIVILEGED_MATCH_TYPE=semver
```

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

### Azure Setup

Source: https://crowci.dev/v5-11/usage/integrations

Commands to create an Azure Service Principal and grant it access to Azure Key Vault.

```bash
# Create a Service Principal
az ad sp create-for-rbac --name crow-ci --skip-assignment

# Note the appId (Client ID), password (Client Secret), and tenant (Tenant ID)

# Grant the Service Principal access to your Key Vault
az keyvault set-policy \
  --name my-vault \
  --spn <appId> \
  --secret-permissions get list
```

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

### Full Jsonnet Example

Source: https://crowci.dev/v5-11/usage/jsonnet

A realistic CI pipeline for a Go project demonstrating Jsonnet functions to eliminate repetition. It includes linting, testing, and multi-database integration tests.

```jsonnet
// Variables used across the pipeline. Unlike YAML anchors, these can be interpolated inside strings.
local golangImage = "golang:1.26-alpine";
local apkDeps = "apk add --no-cache -q just git gcc musl-dev";

// A helper function that generates a step with common defaults.
// In YAML, every step that needs the Go image, the vendor dependency,
// and the apk install line must repeat all of that.
local goStep(name, commands, extra={}) = {
  name: name,
  image: golangImage,
  depends_on: ["vendor"],
  commands: [apkDeps] + commands,
} + extra;

// Database test step generator --- three databases, same structure.
local dbTestStep(name, driver, datasource, extra={}) = goStep(
  name,
  ["just test-server-datastore"],
  {
    environment: {
      CROW_DATABASE_DRIVER: driver,
      CROW_DATABASE_DATASOURCE: datasource,
    },
  } + extra,
);

// The pipeline definition.
{
  when: [
    { event: "pull_request" },
    { event: "push", branch: ["${CI_REPO_DEFAULT_BRANCH}"] },
  ],

  steps: [
    // vendor step has no dependencies and no apk install
    {
      name: "vendor",
      image: golangImage,
      commands: ["go mod vendor"],
    },

    goStep("lint", [
      // Install linter from upstream script to always match the current Go version.
      "wget -O- -nv https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b /usr/local/bin v2.9.0",
      "golangci-lint run",
    ], { when: [{ event: "pull_request" }] }),

    goStep("test", [
      "just test-agent",
      "just test-server",
      "just test-cli",
      "just test-lib",
    ]),

    // Database integration tests
    dbTestStep("sqlite", "sqlite3", "", {
      // Override commands: sqlite uses a coverage variant
      commands: [apkDeps, "just test-server-datastore-coverage"],
    }),
    dbTestStep(
      "postgres", "postgres",
      "host=svc-postgres user=postgres dbname=postgres sslmode=disable",
      { when: [{ event: "pull_request" }] },
    ),
    dbTestStep(
      "mysql", "mysql",
      "root@tcp(svc-mysql:3306)/test?parseTime=true",
      { when: [{ event: "pull_request" }] },
    ),
  ],

  services: [
    {
      name: "svc-postgres",
      image: "postgres:17",
      ports: ["5432"],
      environment: {
        POSTGRES_USER: "postgres",
        POSTGRES_HOST_AUTH_METHOD: "trust",
      },
      when: [{ event: "pull_request" }],
    },
    {
      name: "svc-mysql",
      image: "mysql:9",
      ports: ["3306"],
      environment: {
        MYSQL_DATABASE: "test",
        MYSQL_ALLOW_EMPTY_PASSWORD: "yes",
      },
      when: [{ event: "pull_request" }],
    },
  ],
}
```

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

### Advanced event trigger example

Source: https://crowci.dev/v5-11/usage/pipelines

Example of triggering a workflow for 'pull_request' events and pushes to the default branch.

```yaml
when:
  - event: pull_request
  - event: push
    branch: ${CI_REPO_DEFAULT_BRANCH}

```

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

### Kubernetes Volume Mount Example

Source: https://crowci.dev/v5-11/usage/volumes

Example of referencing a PersistentVolumeClaim (PVC) named 'cache' in Kubernetes steps.

```yaml
steps:
  - name: "step name"
    image: <image>
    volumes:
      - cache:/mnt/cache
    [...]
```

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

### Install the Collection via requirements.yml

Source: https://crowci.dev/v5-11/installation/ansible

Install the devxy.cicd Ansible collection using a requirements.yml file.

```yaml
collections:
  - name: devxy.cicd
    version: <version>
```

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

### Node.js Plugin Example

Source: https://crowci.dev/v5-11/plugins/creating-plugins

A basic Node.js plugin demonstrating how to access environment variables and handle JSON settings.

```javascript
#!/usr/bin/env node
const server = process.env.PLUGIN_SERVER;
const token = process.env.PLUGIN_TOKEN;

if (!server || !token) {
  console.error('Error: SERVER and TOKEN are required');
  process.exit(1);
}

// Handle complex settings
const targets = JSON.parse(process.env.PLUGIN_TARGETS || '[]');

// Plugin logic here
console.log(`Deploying to ${server}`);
targets.forEach(target => console.log(`  - ${target}`));

```

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

### Minimal Plugin Structure

Source: https://crowci.dev/v5-11/plugins/creating-plugins

A basic Dockerfile for a plugin, including installing dependencies, copying the plugin script, and setting the entrypoint.

```dockerfile
FROM alpine:latest

# Install dependencies
RUN apk add --no-cache bash curl

# Copy plugin script
COPY plugin.sh /usr/local/bin/plugin.sh
RUN chmod +x /usr/local/bin/plugin.sh

# Fixed entrypoint - cannot be overridden
ENTRYPOINT ["/usr/local/bin/plugin.sh"]
```

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

### Publishing Plugin to Container Registry

Source: https://crowci.dev/v5-11/plugins/creating-plugins

Commands to build and push a plugin image to a container registry.

```bash
docker build -t codeberg.org/myuser/my-plugin:1.0.0 .
docker push codeberg.org/myuser/my-plugin:1.0.0

```

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

### External Secret (Object) Example

Source: https://crowci.dev/v5-11/usage/integrations

Example of referencing an external secret (e.g., from Vault) using an object value.

```yaml
steps:
  - name: deploy
    image: alpine
    environment:
      # External secret from Vault
      API_KEY:
        from_secret:
          integration: 1              # Integration ID or name
          path: 'crow/myapp'
          key: 'api_key'
```

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

### Internal Secret (String) Example

Source: https://crowci.dev/v5-11/usage/integrations

Example of referencing an internal Crow CI secret using a string value.

```yaml
steps:
  - name: deploy
    image: alpine
    environment:
      # Internal secret from Crow CI
      API_KEY:
        from_secret: my_api_key
```

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

### Infisical Secret Syntax Example

Source: https://crowci.dev/v5-11/usage/integrations

Example of how to reference an Infisical secret within a pipeline step's environment variables.

```yaml
steps:
  - name: deploy
    image: alpine
    environment:
      DB_PASSWORD:
        from_secret:
          integration: "infisical-prod"
          path: 'DATABASE_PASSWORD'   # Infisical secret key name
          key: 'value'                # Convention for single-valued secrets
```

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

### Start Crow with Docker Compose

Source: https://crowci.dev/v5-11/installation/container

Command to start Crow CI services in detached mode.

```bash
docker compose up -d
```

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

### Using External Secrets in Plugin Settings Example

Source: https://crowci.dev/v5-11/usage/integrations

Example showing how external secrets can be used in plugin settings, not just environment variables.

```yaml
steps:
  - name: publish
    image: codefloe.com/crowci/buildx:latest
    settings:
      registry: registry.example.com
      repo: myorg/myapp
      tags: <your-tag>
      username: myuser
      password:
        from_secret:
          integration: 1
          path: 'crow/docker'
          key: 'password'
```

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

### Crow Server Configuration Example

Source: https://crowci.dev/v5-11/configuration/server

Example of setting the external configuration service endpoint in the Crow server configuration.

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

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

### Example Agent Environment Variables

Source: https://crowci.dev/v5-11/configuration/autoscaler

An example of environment variables that can be passed to spawned agents, including labels and log level.

```shell
CROW_AGENT_ENV=CROW_AGENT_LABELS=tier=heavy,CROW_LOG_LEVEL=debug,CROW_HEALTHCHECK=false
```

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

### Go Plugin Main Function

Source: https://crowci.dev/v5-11/plugins/creating-plugins

A Go program demonstrating how to access environment variables for plugin settings and perform basic validation.

```go
package main

import (
    "fmt"
    "os"
)

func main() {
    server := os.Getenv("PLUGIN_SERVER")
    token := os.Getenv("PLUGIN_TOKEN")

    if server == "" || token == "" {
        fmt.Println("Error: SERVER and TOKEN are required")
        os.Exit(1)
    }

    // Plugin logic here
    fmt.Printf("Deploying to %s\n", server)
}
```

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

### Versioning and Tagging Plugin Images

Source: https://crowci.dev/v5-11/plugins/creating-plugins

Commands to tag and push plugin images with specific versions and aliases.

```bash
docker tag my-plugin:1.2.3 my-plugin:1
docker tag my-plugin:1.2.3 my-plugin:1.2
docker push my-plugin:1.2.3
docker push my-plugin:1.2
docker push my-plugin:1

```

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

### Bitbucket Cloud - Multi-Forge Configuration

Source: https://crowci.dev/v5-11/configuration/forge-oauth

Environment variables for configuring Crow CI with Bitbucket Cloud in a multi-forge setup.

```bash
CROW_FORGES=bitbucket
CROW_FORGE_BITBUCKET_TYPE=bitbucket
CROW_FORGE_BITBUCKET_CLIENT=<key>
CROW_FORGE_BITBUCKET_SECRET=<secret>
```

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

### Running Tests

Source: https://crowci.dev/v5-11/development/building

Commands to run all tests or component-specific tests, including database migrations and frontend tests.

```bash
# Run all tests
just test

# Run component-specific tests
just test-server
just test-agent
just test-cli

# Test database migrations
just test-server-datastore

# Run frontend tests
just test-ui
```

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

### Self-Hosted GitLab Forge URL Configuration (Multi-Forge)

Source: https://crowci.dev/v5-11/configuration/forge-oauth

Additional configuration for self-hosted GitLab when using multi-forge setup.

```shell
# Multi-forge
CROW_FORGE_GITLAB_URL=https://gitlab.example.com
```

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

### GitHub Enterprise Forge URL Configuration (Multi-Forge)

Source: https://crowci.dev/v5-11/configuration/forge-oauth

Additional configuration for GitHub Enterprise when using multi-forge setup.

```shell
# Multi-forge
CROW_FORGE_GITHUB_URL=https://github.example.com
```

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

### Local Testing with Docker

Source: https://crowci.dev/v5-11/plugins/creating-plugins

Command to build and run a plugin locally using Docker, setting necessary environment variables.

```bash
docker build -t my-plugin .

docker run --rm \
  -e PLUGIN_SERVER=https://api.example.com \
  -e PLUGIN_TOKEN=test-token \
  -e PLUGIN_MESSAGE="Hello World" \
  my-plugin

```

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

### Mixing Internal and External Secrets Example

Source: https://crowci.dev/v5-11/usage/integrations

Example illustrating how to use both internal Crow CI secrets and external secrets from integrations within the same pipeline step.

```yaml
steps:
  - name: build
    image: alpine
    environment:
      # Internal secret from Crow CI (string value)
      INTERNAL_TOKEN:
        from_secret: my_token
      # External secret from Vault (object value)
      EXTERNAL_API_KEY:
        from_secret:
          integration: "vault-prod"
          path: 'crow/api'
          key: 'key'
```

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

### Docker Volume Mount Example

Source: https://crowci.dev/v5-11/usage/volumes

Example of defining volume mounts in the YAML config file for the Docker backend, mounting host directories into pipeline containers.

```yaml
steps:
  - name: build
    [...]
    volumes:
      - /etc/ssl/certs:/etc/ssl/certs
```

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

### Parsing Complex Settings

Source: https://crowci.dev/v5-11/plugins/creating-plugins

Bash script showing how to parse JSON-serialized array and object settings using `jq`.

```bash
#!/bin/bash
# Parse JSON array
TARGETS=$(echo "$PLUGIN_TARGETS" | jq -rRs '. as $raw | try (fromjson | .[]) catch $raw')

# Parse JSON object
RETRIES=$(echo "$PLUGIN_CONFIG" | jq -r '.retries')
```

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

### Self-hosted Forge Behind Proxy - Multi-Forge

Source: https://crowci.dev/v5-11/configuration/forge-oauth

Explicitly setting the OAuth host for a multi-forge setup with a self-hosted forge behind a proxy.

```bash
# Multi-forge
CROW_FORGE_{NAME}_OAUTH_HOST=https://git.public.example.com
```