### First Pipeline Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/quickstart.mdx

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

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

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

### Verify Installation

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/development/setup.mdx

Commands to verify the installation of Go, Bun, and Just, and to run linters.

```shell
# Check Go
go version

# Check Bun
bun --version

# Check Just
just --version

# Run linters
just lint
```

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

### Quick Start Commands

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/development/index.mdx

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

```shell
# 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 Go Dependencies

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/development/setup.mdx

Installs Go-related dependencies using the 'just' task runner.

```shell
just install-dev-deps
```

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

### Install Frontend Dependencies

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/development/setup.mdx

Installs frontend dependencies using Bun after navigating to the 'web' directory.

```shell
cd web
bun install
```

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

### docker-compose.yml

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/quickstart.mdx

Example docker-compose.yml file for setting 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:

```

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

### Setup Pre-commit Hooks

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/development/setup.mdx

Installs pre-commit hooks for Git.

```shell
pre-commit install
```

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

### Set up and Start Service

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/installation/binary.mdx

Commands to create necessary directories, set permissions, and load/start the Crow agent service.

```bash
# Create working directories
sudo mkdir -p /usr/local/var/crow-agent /usr/local/var/log

# Set proper permissions on the plist file
sudo chown root:wheel /Library/LaunchDaemons/crowci.agent.plist
sudo chmod 644 /Library/LaunchDaemons/crowci.agent.plist

# Load and start the service (bootstrap will start it automatically)
sudo launchctl bootstrap system /Library/LaunchDaemons/crowci.agent.plist

# Verify the service is running
sudo launchctl list | grep crowci

# View logs
tail -f /usr/local/var/log/crow-agent.log
tail -f /usr/local/var/log/crow-agent-error.log
```

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

### Local Server Configuration Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/installation/binary.mdx

Alternative configuration for connecting to a local server without TLS.

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

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

### Example: Multi-Forge Setup

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/configuration/env-vars/forge.mdx

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

```bash
# 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
```

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

### Full example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/services.mdx

Full example of services configuration.

```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
```

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

### Container Image Installation

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/cli.mdx

Install the CLI using the container image.

```bash
docker run --pull always \
  -e CROW_TOKEN=$CROW_TOKEN \
  -e CROW_SERVER=$CROW_SERVER \
  --rm -it codefloe.com/crowci/crow-cli:dev info
```

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

### Quick Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/plugins/index.mdx

This example demonstrates how to configure a plugin within a CI/CD workflow. The `settings` key is used to pass configuration parameters to the plugin, which are then exposed as environment variables.

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

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

### Tmpfs Mount Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/workflow-syntax.mdx

Example of how to configure tmpfs mounts for a service in a workflow.

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

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

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

### macOS (launchd) Plist Configuration

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/installation/binary.mdx

Example plist file content for running the Crow agent as a system service on macOS 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>
```

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

### Install the chart

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/installation/helm.mdx

Installs the Crow CI Helm chart from the added repository.

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

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

### Crow CI Go Client Example

Source: https://github.com/crowci/crow/blob/main/crow-go/README.md

Example demonstrating how to use the crow-go client to authenticate with Crow CI and perform basic operations like fetching user information and repository details.

```Go
import (
  "codefloe.com/crowci/crow/v5/crow-go/crow"
  "golang.org/x/oauth2"
)

const (
  token = "dummyToken"
  host  = "http://crow.company.tld"
)

func main() {
  // create an http client with oauth authentication.
  config := new(oauth2.Config)
  authenticator := config.Client(
    oauth2.NoContext,
    &oauth2.Token{
      AccessToken: token,
    },
  )

  // create the crow client with authenticator
  client := crow.NewClient(host, authenticator)

  // gets the current user
  user, err := client.Self()
  fmt.Println(user, err)

  // gets the named repository information
  repo, err := client.RepoLookup("crow-ci/crow")
  fmt.Println(repo, err)
}
```

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

### Correct Plugin Configuration (Settings)

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/plugins/using-plugins.mdx

Example of correct usage of `settings:` for plugins.

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

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

### Matrix Workflow Basic Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/pipelines.mdx

Example of a matrix workflow defining different GO_VERSION and REDIS_VERSION combinations.

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

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

### runs_on example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/workflow-syntax.mdx

Example of configuring a workflow to run on success or failure.

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

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

### Full Jsonnet Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/jsonnet.mdx

A comprehensive Jsonnet example demonstrating a Go project CI pipeline with linting, testing, and multi-database integration tests, utilizing functions to reduce repetition.

```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" }],
    },
  ],
}

```

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

### Persisting Environment Variables Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/advanced.mdx

An example of initializing environment variables in one step and sourcing them in subsequent steps.

```yaml
steps:
  - name: init
    image: bash
    commands:
      - echo "FOO=hello" >> envvars
      - echo "BAR=world" >> envvars

  - name: debug
    image: bash
    commands:
      - source envvars
      - echo $FOO
```

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

### Enable and start Podman socket service for rootless Podman

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/configuration/env-vars/backend-podman.mdx

For rootless Podman, ensure the Podman socket service is enabled and started.

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

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

### Privileged Plugin Image Matching Example (semver)

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/workflow-syntax.mdx

Example of setting environment variables to allow specific plugin images to run in privileged mode using semver matching.

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

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

### Install using OCI

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/installation/helm.mdx

Installs the Crow CI Helm chart directly using OCI.

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

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

### Docker Compose docker-compose.yml example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/installation/container.mdx

Example docker-compose.yml file for deploying Crow CI server and agent.

```yaml
services:
  server:
    image: codefloe.com/crowci/crow-server:<version>
    ports:
      - "8000:8000"
    volumes:
      - crow-server:/var/lib/crow
    environment:
      - CROW_OPEN=true
      - CROW_HOST=${CROW_HOST}
      - CROW_AGENT_SECRET=${CROW_AGENT_SECRET}
      - CROW_GITHUB=true
      - CROW_GITHUB_CLIENT=${CROW_GITHUB_CLIENT}
      - CROW_GITHUB_SECRET=${CROW_GITHUB_SECRET}

  agent:
    image: codefloe.com/crowci/crow-agent:<version>
    restart: always
    depends_on:
      - server
    volumes:
      - crow-agent:/etc/crow
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - CROW_SERVER=server:9000
      - CROW_AGENT_SECRET=${CROW_AGENT_SECRET}

volumes:
  crow-server:
  crow-agent:
```

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

### Docker Backend Options

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/configuration/server.mdx

Example of configuring Docker backend options for steps.

```yaml
steps:
  - name: test
    image: alpine
    backend_options:
      docker:
        user: 10000:10000
```

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

### Jsonnet library example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/jsonnet.mdx

Example of a Jsonnet library file (`.libsonnet`) defining reusable components.

```jsonnet
{ 
  goImage: "golang:1.23",
  step(name, commands):: {
    name: name,
    image: $.goImage,
    commands: commands,
  },
}
```

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

### Privileged Plugin Image Matching Example (exact)

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/workflow-syntax.mdx

Example of setting environment variables to allow a specific plugin image to run in privileged mode using exact matching.

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

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

### Adding a New Migration Example

Source: https://github.com/crowci/crow/blob/main/CLAUDE.md

Example of how to add a new migration entry to the `Migrate()` function in `migration.go`.

```go
{
    ID: "crow-describe-change",
    Migrate: func(tx *sql.Tx) error {
        _, err := tx.Exec("ALTER TABLE repos ADD COLUMN new_col TEXT")
        return err
    }},

```

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

### Privileged Plugin Image Matching Example (regex)

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/workflow-syntax.mdx

Example of setting environment variables to allow specific plugin images to run in privileged mode using regex matching.

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

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

### Privileged Plugin Image Matching Example (semver-range)

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/workflow-syntax.mdx

Example of setting environment variables to allow specific plugin images to run in privileged mode using semver-range matching.

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

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

### Podman Backend Options

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/configuration/server.mdx

Example of configuring Podman backend options for steps.

```yaml
steps:
  - name: test
    image: alpine
    backend_options:
      podman:
        user: 10000:10000
```

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

### Running Single Tests

Source: https://github.com/crowci/crow/blob/main/CLAUDE.md

Examples of how to run single tests with Go.

```bash
go test -v -run TestName ./path/to/package
go test -tags 'test' -run TestName ./path/to/package
go test -v -run TestPipeline codeberg.org/crowci/crow/v5/server/pipeline
```

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

### CLI linting with Jsonnet

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/jsonnet.mdx

Command-line examples for linting Jsonnet configuration files.

```bash
crow-cli lint .crow.jsonnet
crow-cli lint .crow/
```

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

### Validate Plist File

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/installation/binary.mdx

Command to validate the syntax of the launchd plist file.

```bash
plutil -lint /Library/LaunchDaemons/crowci.agent.plist
```

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

### Go Plugin Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/plugins/creating-plugins.mdx

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

```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)
}
```

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

### Conditional Execution: Git Reference Filter

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/workflow-syntax.mdx

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

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

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

### Security: Recommended Settings Usage

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/v5-11/plugins/creating-plugins.mdx

Example demonstrating the correct approach of using `settings:` to pass sensitive information to a plugin.

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

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

### macOS Installation

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/installation/binary.mdx

Download, extract, and install the Crow 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
```

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

### Install the Collection

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/installation/ansible.mdx

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

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

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

### Security Best Practice: Settings vs. Environment

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/plugins/creating-plugins.mdx

Illustrates the correct approach of using `settings:` for plugin inputs, contrasting it with the disallowed `environment:` approach for security reasons.

```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
```

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

### Workflow Dependency Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/pipelines.mdx

Example of a workflow with explicit dependencies on other workflows.

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

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

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

### List Repositories

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/v5-11/usage/cli.mdx

List all repositories.

```sh
# List repositories
crow repo ls
```

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

### skip_clone example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/workflow-syntax.mdx

Example of skipping the implicit clone step in a workflow.

```yaml
skip_clone: true
```

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

### Versioning and Tagging Plugin Images

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/plugins/creating-plugins.mdx

Demonstrates how to tag Docker images for specific versions and major version aliases, and push them to a registry.

```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

```

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

### Basic Plugin Usage

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/plugins/using-plugins.mdx

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!"
```

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

### List Repositories

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/cli.mdx

List all repositories accessible by the authenticated user.

```bash
crow repo ls
```

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

### Event Trigger Example (Push)

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/pipelines.mdx

Example of a workflow triggered by a push event.

```yaml
when:
  event: push
```

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

### Simple Settings Conversion

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/plugins/using-plugins.mdx

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"
```

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

### Install the Collection via requirements.yml

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/v5-11/installation/ansible.mdx

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

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

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

### File Tree Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/pipelines.mdx

Example of a file tree defining four workflows within the .crow/ directory.

```tree
.crow/
├── build.yaml
├── deploy.yaml
├── lint.yaml
└── test.yaml
```

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

### Building Binaries

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/development/building.mdx

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

```shell
# Build server
just build-server

# Build agent
just build-agent

# Build CLI
just build-cli

# Build UI
just build-ui
```

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

### Secret Handling: Good Practice Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/plugins/creating-plugins.mdx

A bash script demonstrating how to handle secrets securely by checking for their existence without logging them.

```bash
#!/bin/bash

# Bad - logs the token
echo "Using token: ${PLUGIN_TOKEN}"

# Good - confirms token exists without exposing it
if [[ -z "${PLUGIN_TOKEN}" ]]; then
  echo "Error: TOKEN setting is required"
  exit 1
fi
echo "Token configured ✓"
```

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

### Docker Compose start command

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/installation/container.mdx

Command to start Crow CI using Docker Compose.

```shell
docker compose up -d
```

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

### Complete Autoscaler Configuration Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/configuration/autoscaler.mdx

A comprehensive example of a docker-compose.yaml file for setting up and configuring the Crow CI Autoscaler, including server connection, scaling limits, gRPC settings, timeouts, and cloud provider-specific configurations (Hetzner Cloud 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
```

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

### Response Format: New Configs

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/configuration/server.mdx

Example JSON response for returning new configurations.

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

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

### Matrix Workflow Include Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/pipelines.mdx

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

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

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

### Go Plugin Main Logic

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/v5-11/plugins/creating-plugins.mdx

A Go program demonstrating how to access environment variables for plugin configuration 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)
}
```

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

### Example Agent Environment Variables

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/configuration/autoscaler.mdx

An example of how to set environment variables for spawned agents using the CROW_AGENT_ENV variable.

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

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

### Crow Server Configuration Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/configuration/server.mdx

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

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

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

### Kubernetes Volume Mount Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/volumes.mdx

Example of referencing a PersistentVolumeClaim (PVC) named 'cache' in a pipeline step for the Kubernetes backend.

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

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

### Node.js Plugin Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/plugins/creating-plugins.mdx

A basic Node.js script demonstrating how a plugin can access environment variables for configuration and perform its logic.

```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}`));

```

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

### Dynamic Config Service Example

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/configuration/server.mdx

A Go service that injects a security scanning step into the build configuration for main branch pushes.

```go
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)
}
```

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

### Self-hosted forge behind a proxy - Multi-Forge

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/configuration/forge-oauth.mdx

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

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

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

### Bitbucket Cloud - Multi-Forge Configuration

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/configuration/forge-oauth.mdx

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>
```

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

### Show All Commands Help

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/cli.mdx

Display help for all available CLI commands.

```bash
crow --help
```

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

### Event Trigger Example (Pull Request and Push to Default Branch)

Source: https://github.com/crowci/crow/blob/main/docs/src/content/docs/dev/usage/pipelines.mdx

Example of a workflow triggered by pull_request events or pushes to the default branch.

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