### Setup and Verify Crow CI Agent macOS System Service

Source: https://crowci.dev/4.5/installation/binary

This snippet outlines the steps to set up and verify the Crow CI agent service on macOS after creating the `launchd` plist file. It includes creating necessary directories, setting correct permissions for the plist file, loading and starting the service via `launchctl`, and confirming its running status. It also shows how to view the agent's logs.

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

```

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

### Prometheus Namespace and Pod Monitor Selector Configuration

Source: https://crowci.dev/4.5/installation/helm

Example Prometheus configuration snippets to ensure metrics are collected from all namespaces and all pod monitors are enabled.

```yaml
# Search all available namespaces
podMonitorNamespaceSelector:
  matchLabels: {}
# Enable all available pod monitors
podMonitorSelector:
  matchLabels: {}
```

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

### Full CrowCI Pipeline Example with Service Configuration and Initialization Wait

Source: https://crowci.dev/4.5/usage/services

A comprehensive example of a CrowCI pipeline demonstrating service configuration, including environment variables for a MySQL database, and a step that waits for the database to initialize before executing commands. This addresses scenarios where services require a delay before they are fully operational.

```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 Crow CI Helm Chart (OCI)

Source: https://crowci.dev/4.5/installation/helm

Installs the Crow CI Helm chart using the OCI registry. This is the recommended installation method.

```bash
helm install crow oci://codeberg.org/crowci/crow
```

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

### Export CROW_PLUGINS_PRIVILEGED with regex match type

Source: https://crowci.dev/4.5/usage/workflow-syntax

This example shows how to configure privileged plugins using the 'regex' match type. It allows any 'crow-plugins/docker-buildx' image with a tag starting with '1.' to be used in privileged mode.

```shell
export CROW_PLUGINS_PRIVILEGED="codeberg.org/crow-plugins/docker-buildx:1\..*"
export CROW_PLUGINS_PRIVILEGED_MATCH_TYPE=regex
```

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

### Example of Complex Plugin Settings (YAML)

Source: https://crowci.dev/4.5/plugins

Demonstrates how to define complex settings for a CrowCI plugin, including nested objects and lists. These settings are converted into a JSON string and passed as an environment variable.

```yaml
settings:
  complex:
    abc: 2
    list:
      - 2
      - 3
```

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

### CrowCI Agent Basic Configuration (Shell)

Source: https://crowci.dev/4.5/installation

Basic configuration settings for a CrowCI agent, including server address, GRPC address, security settings, and optional labels.

```shell
# (optional) agent labels to restrict workflows processing to matching labels
CROW_AGENT_LABELS: <labels>
# [...] additional agent settings
```

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

### Install Crow CI Helm Chart (Classical Repo)

Source: https://crowci.dev/4.5/installation/helm

Installs the Crow CI Helm chart using a classical Helm repository. This method requires adding the repository first.

```bash
helm repo add crowci https://codeberg.org/api/packages/crowci/helm
helm install crow crowci/crow
```

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

### Matrix Workflow Interpolation Example

Source: https://crowci.dev/4.5/usage/pipelines

Demonstrates how matrix variables are interpolated into the YAML configuration before parsing. This example shows how `${VARIABLE}` syntax is used for image tags and environment variables.

```yaml
matrix:
  GO_VERSION:
    - 1.4
    - 1.3
  DATABASE:
    - mysql:8
    - mysql:5
    - mariadb:10.1

steps:
  - name: build
    image: golang:${GO_VERSION}
    commands:
      - go get
      - go build
      - go test

services:
  - name: database
    image: ${DATABASE}
```

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

### Configure Public GRPC Ingress for External Agents

Source: https://crowci.dev/4.5/installation/helm

Example Helm values to enable a TLS-enabled GRPC ingress for external agents to register with the server. Requires `ingress-nginx` and a cert-manager DNS issuer.

```yaml
server:
  env:
    CROW_GRPC_SECURE: "true"

ingress:
 grpc:
   enabled: true
   annotations:
     cert-manager.io/cluster-issuer: 'letsencrypt-dns01-prod'
     kubernetes.io/ingress.class: nginx
   hosts:
     - host: grpc.example.com
       paths:
         - path: /
   tls:
     - hosts:
         - grpc.grpc.example.com
       secretName: grpc.grpc.example.com-tls
```

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

### Export CROW_PLUGINS_PRIVILEGED with exact match type

Source: https://crowci.dev/4.5/usage/workflow-syntax

This example configures privileged plugins using the 'exact' match type, ensuring only the precise image 'codeberg.org/crow-plugins/docker-buildx:1.0.0' is allowed to run in privileged mode.

```shell
export CROW_PLUGINS_PRIVILEGED="codeberg.org/crow-plugins/docker-buildx:1.0.0"
export CROW_PLUGINS_PRIVILEGED_MATCH_TYPE=exact
```

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

### Use CrowCI Ansible Role

Source: https://crowci.dev/4.5/installation/ansible

Demonstrates how to incorporate the CrowCI role into an Ansible playbook. It specifies the role and provides a placeholder for variable definitions.

```yaml
- name: Crow CI
  vars:
    - [...]
  roles:
    - role: devxy.cicd.crowci
```

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

### Customize CrowCI Service Containers with Environment Variables

Source: https://crowci.dev/4.5/usage/services

Shows how to use the 'environment' section to pass environment variables for customizing the startup of service containers in CrowCI. This is useful for configuring database credentials, settings, or other service-specific parameters. The example demonstrates setting MySQL database name and allowing empty passwords.

```yaml
services:
  - name: database
    image: mysql
    environment:
      - MYSQL_DATABASE=test
      - MYSQL_ALLOW_EMPTY_PASSWORD=yes

  - name: cache
    image: redis

```

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

### Handle CrowCI Service Initialization Delays with Sleep

Source: https://crowci.dev/4.5/usage/services

Provides a solution for service initialization delays in CrowCI pipelines when 'detach' is not suitable. By adding a 'sleep' command before other steps, you can ensure the service is ready to accept connections before being used. The example includes a 15-second sleep before package installation and testing.

```yaml
steps:
  - name: test
    image: golang
    commands:
      - sleep 15
      - go get
      - go test

services:
  - name: database
    image: mysql

```

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

### Tunnelmole Command for Reverse Proxy

Source: https://crowci.dev/4.5/installation/proxy

Demonstrates how to use `tunnelmole` to create a secure tunnel to Crow. It involves running the `tmole` command with the Crow port and then setting the `CROW_HOST` environment variable to the provided URL.

```bash
tmole 8000
http://bvdo5f-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:8000
https://bvdo5f-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:8000
```

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

### Install Crow CI Agent Binary on macOS

Source: https://crowci.dev/4.5/installation/binary

This snippet downloads, extracts, and installs the Crow CI agent binary for macOS. It sets environment variables for the version and architecture, fetches the binary using curl, extracts the tarball, and moves the executable to a system path for general accessibility. Finally, it verifies the installation by checking the agent version.

```shell
export VERSION=4.3.0
export ARCH=arm64
curl -LO https://codeberg.org/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

```

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

### Export CROW_PLUGINS_PRIVILEGED with semver match type

Source: https://crowci.dev/4.5/usage/workflow-syntax

This example demonstrates setting privileged plugins using the 'semver' match type. It allows any 'crow-plugins/docker-buildx' image with a major version 1 tag and any 'plugins/gcr' image with a 7.2.x tag to run in privileged mode.

```shell
export CROW_PLUGINS_PRIVILEGED="codeberg.org/crow-plugins/docker-buildx:1,plugins/gcr:7.2"
export CROW_PLUGINS_PRIVILEGED_MATCH_TYPE=semver
```

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

### Export CROW_PLUGINS_PRIVILEGED with semver-range match type

Source: https://crowci.dev/4.5/usage/workflow-syntax

This example demonstrates setting privileged plugins with the 'semver-range' match type. It permits any 'crow-plugins/docker-buildx' image with a version from 1.0.0 (inclusive) up to 2.0.0 (exclusive) to run in privileged mode.

```shell
export CROW_PLUGINS_PRIVILEGED="codeberg.org/crow-plugins/docker-buildx:>=1.0.0,<2.0.0"
export CROW_PLUGINS_PRIVILEGED_MATCH_TYPE=semver-range
```

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

### Matrix Pipeline for Multiple Platforms

Source: https://crowci.dev/4.5/usage/pipelines

Example of a matrix pipeline used for testing across different platforms. It includes a conditional trigger for a specific platform using the 'when' clause.

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

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

### Define Service Containers with Hostnames in CrowCI

Source: https://crowci.dev/4.5/usage/services

Demonstrates how to define 'service' containers in the CrowCI pipeline configuration. These services, such as databases or caches, are accessible via assigned hostnames within the pipeline. The example shows setting up a 'database' service using the 'mysql' image.

```yaml
steps:
  - name: build
    image: golang
    commands:
      - go build
      - go test

services:
  - name: database
    image: mysql

  - name: cache
    image: redis

```

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

### Configure Ports and Protocols for CrowCI Services

Source: https://crowci.dev/4.5/usage/services

Illustrates how to specify the ports and protocols for service containers in CrowCI pipelines. This allows defining which ports the service will expose and the protocol (e.g., UDP) it uses. The example shows configuring ports for a 'database' (MySQL) and a 'wireguard' service.

```yaml
services:
  - name: database
    image: mysql
    ports:
      - 3306

  - name: wireguard
    image: wg
    ports:
      - 51820/udp

```

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

### Enable Metrics Collection

Source: https://crowci.dev/4.5/installation/helm

Helm values to enable metrics gathering on port 9001 and configure Prometheus pod monitoring.

```yaml
metrics:
  enabled: true
  port: 9001

prometheus:
  podmonitor:
    enabled: true
    interval: 60s
    labels: {}
```

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

### Configure Crow CI Agent as a macOS launchd Service

Source: https://crowci.dev/4.5/installation/binary

This snippet provides the XML configuration for a macOS launchd plist file to run the Crow CI agent as a system service. It specifies the agent executable path, environment variables for server connection (including secure gRPC or local IP), logging paths, and service lifecycle management (RunAtLoad, KeepAlive). Ensure `CROW_SERVER` and `CROW_AGENT_SECRET` are updated with your specific values. For local servers without TLS, adjust `CROW_SERVER` and remove gRPC related keys.

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

```

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

```

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

### Caddy Server and gRPC Reverse Proxy Configuration

Source: https://crowci.dev/4.5/installation/proxy

Sets up Caddy as a reverse proxy for both standard HTTP and gRPC traffic for Crow. The 'Server' configuration handles regular web requests, while the 'GRPC' configuration is for remote agents connecting over the public internet.

```caddy
crow.example.com {
  reverse_proxy crow-server:8000
}
```

```caddy
grpc.crow.example.com {
  reverse_proxy h2c://crow-server:9000
}
```

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

### Trigger Workflow on Multiple Events and Branch

Source: https://crowci.dev/4.5/usage/pipelines

Specifies multiple conditions for triggering a workflow. This example triggers a workflow for 'pull_request' events and for 'push' events to the default branch.

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

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

### Traefik Docker Compose Configuration for Crow

Source: https://crowci.dev/4.5/installation/proxy

Provides a Traefik configuration using Docker Compose for Crow, including TLS termination and HTTP to HTTPS redirection. It sets up services for both the main server and gRPC endpoints, using labels to define routing rules and ports.

```yaml
services:
  server:
    image: <image>
    environment:
      # [..] Crow settings
    networks:
      - dmz # externally defined network, so that traefik can connect to the server
    volumes:
      - crow-server-data:/var/lib/crow/
    deploy:
      labels:
        - traefik.enable=true

        # web server
        - traefik.http.services.crow-service.loadbalancer.server.port=8000

        - traefik.http.routers.crow-secure.rule=Host(`cd.your-domain.com`)
        - traefik.http.routers.crow-secure.tls=true
        - traefik.http.routers.crow-secure.tls.certresolver=letsencrypt
        - traefik.http.routers.crow-secure.entrypoints=web-secure
        - traefik.http.routers.crow-secure.service=crow-service

        - traefik.http.routers.crow.rule=Host(`cd.your-domain.com`)
        - traefik.http.routers.crow.entrypoints=web
        - traefik.http.routers.crow.service=crow-service

        - traefik.http.middlewares.crow-redirect.redirectscheme.scheme=https
        - traefik.http.middlewares.crow-redirect.redirectscheme.permanent=true
        - traefik.http.routers.crow.middlewares=crow-redirect@docker

networks:
  dmz:
    external: true
```

```yaml
# [...] continued from previous block
        - traefik.http.services.crow-grpc.loadbalancer.server.port=9000
        - traefik.http.services.crow-grpc.loadbalancer.server.scheme=h2c

        - traefik.http.routers.crow-grpc-secure.rule=Host(`grpc.crow.example.com`)
        - traefik.http.routers.crow-grpc-secure.tls=true
        - traefik.http.routers.crow-grpc-secure.tls.certresolver=letsencrypt
        - traefik.http.routers.crow-grpc-secure.entrypoints=web-secure
        - traefik.http.routers.crow-grpc-secure.service=crow-grpc

        - traefik.http.routers.crow-grpc.rule=Host(`grpc.crow.example.com`)
        - traefik.http.routers.crow-grpc.entrypoints=web
        - traefik.http.routers.crow-grpc.service=crow-grpc

        - traefik.http.middlewares.crow-grpc-redirect.redirectscheme.scheme=https
        - traefik.http.middlewares.crow-grpc-redirect.redirectscheme.permanent=true
        - traefik.http.routers.crow-grpc.middlewares=crow-grpc-redirect@docker

networks:
  dmz:
    external: true
```

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

### HAProxy Backend Configuration (CrowCI gRPC)

Source: https://crowci.dev/4.5/installation/proxy

Sets up the backend server for the CrowCI gRPC service. It configures the server to handle HTTP mode, specifies the gRPC server address, connection limits, and enables HTTP/2 protocol support without health checks.

```haproxy
backend crowci_grpc_backend
    mode http
    server crowci_grpc 0.0.0.0:9000 maxconn 100000 no-check proto h2

```

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

### HAProxy Frontend Configuration (HTTP/HTTPS)

Source: https://crowci.dev/4.5/installation/proxy

Defines the frontend listener for incoming HTTP/HTTPS traffic. It binds to port 443, handles SSL termination, and uses Access Control Lists (ACLs) to route traffic to different backends based on the 'Host' header.

```haproxy
frontend https_in
    mode http
    bind :::443 v4v6 ssl crt <cert>

    acl is_ci_subdomain hdr(host) -i crow.example.com
    acl is_grpc_ci_subdomain hdr(host) -i grpc.crow.example.com

    use_backend crowci_backend if is_ci_subdomain
    use_backend crowci_grpc_backend if is_grpc_ci_subdomain

```

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

### HAProxy Backend Configuration (CrowCI HTTP)

Source: https://crowci.dev/4.5/installation/proxy

Configures the backend server for the main CrowCI HTTP application. It sets the mode to HTTP, uses round-robin load balancing, forwards the client's IP address, and defines the server address and connection limits.

```haproxy
backend crowci_backend
    mode http
    balance roundrobin

    http-request del-header X-Forwarded-For
    http-request del-header X-Real-IP
    # add an X-Forwarded-For header to the request, containing the actual IP address of the client
    option forwardfor

    server crowci 0.0.0.0:8000 maxconn 100000 check

```

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

### YAML Anchors and Aliases for Reusability

Source: https://crowci.dev/4.5/usage/advanced

Anchors (&) define reusable YAML nodes, while aliases (*) reference them. This is useful for repeating configurations like Docker images across multiple pipeline steps, reducing redundancy. The example shows how to define a Golang image anchor and reuse it.

```yaml
variables:
  - &golang_image 'golang:1.18' # anchor

 steps:
   - name: test
     image: *golang_image # alias

   - name: build
     image: *golang_image # alias
     (...)

```

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

### Docker Compose Configuration for Crow CI Autoscaler with Scaling Parameters

Source: https://crowci.dev/4.5/configuration/autoscaler

This Docker Compose configuration extends the basic autoscaler setup by including environment variables to define scaling parameters. `CROW_MIN_AGENTS` and `CROW_MAX_AGENTS` control the number of instances, while `CROW_WORKFLOWS_PER_AGENT` determines parallel processing capacity per agent.

```yaml
crow-autoscaler:
  image: codeberg.org/crowci/crow-autoscaler:<tag>
  restart: always
  depends_on:
    - crow-server
  environment:
    - CROW_SERVER=crow-server:9000 # can also be the public URL (https://)
    - CROW_TOKEN=${CROW_TOKEN}
    - CROW_AUTOSCALER_TOKEN=${CROW_AUTOSCALER_TOKEN}
    - CROW_MIN_AGENTS=0
    - CROW_MAX_AGENTS=1
    - CROW_WORKFLOWS_PER_AGENT=5

```

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

### CrowCI Agent Configuration for Public Route (Shell)

Source: https://crowci.dev/4.5/installation

Configuration for a CrowCI agent when using the public route, requiring a secure SSL-GRPC connection. This setup ensures secure communication between the agent and the Crow server by utilizing a TLS-ready ingress.

```shell
CROW_SERVER: crow.mydomain.com
CROW_GRPC_ADDR: grpc.crow.mydomain.com
CROW_GRPC_SECURE: 'true'
# agent token, previously created in Crow server
CROW_AGENT_SECRET: <token>
# (optional) agent labels to restrict workflows processing to matching labels
CROW_AGENT_LABELS: <labels>
# [...] additional agent settings
```

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

### String Setting Conversion to Environment Variable (CrowCI)

Source: https://crowci.dev/4.5/plugins

Shows how a simple string setting in CrowCI is converted into an environment variable with a 'PLUGIN_' prefix. The string value is preserved.

```yaml
some-String: hello
# Becomes PLUGIN_SOME_STRING="hello"
```

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

### Default Entrypoint Configuration

Source: https://crowci.dev/4.5/usage/workflow-syntax

Shows the default entrypoint configuration used by CrowCI, which decodes a Base64-encoded script and executes it with `/bin/sh -e`.

```json
"/bin/sh", "-c", "echo $CI_SCRIPT | base64 -d | /bin/sh -e"

```

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

### Filter by Git Reference (ref) - CrowCI

Source: https://crowci.dev/4.5/usage/workflow-syntax

The 'ref' filter allows workflows to be triggered based on Git references, such as tags. It uses glob patterns to match references. For example, to filter tags starting with 'v', a pattern like 'refs/tags/v*' is used.

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

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

### Nginx Server and gRPC Reverse Proxy Configuration

Source: https://crowci.dev/4.5/installation/proxy

Configures Nginx as a reverse proxy for Crow, including SSL termination and request forwarding. This example focuses on routing traffic to Crow's web interface and gRPC endpoint, requiring SSL certificates.

```nginx
server {
    listen 443 ssl; 
    server_name crow.example.com; 

    ssl_certificate path/to/cert; 
    ssl_certificate_key path/to/key; 

    location / {
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;

        proxy_pass http://0.0.0.0:8000;
        proxy_redirect off;
        proxy_http_version 1.1;
        proxy_buffering off;

        chunked_transfer_encoding off;
    }
}
```

```nginx
server {
    listen 443 ssl;
    server_name grpc.example.com;

    ssl_certificate path/to/cert;
    ssl_certificate_key path/to/key;

    location / {
      grpc_pass grpc://0.0.0.0:9000;
    }
}
```

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

### Integer Setting Conversion to Environment Variable (CrowCI)

Source: https://crowci.dev/4.5/plugins

Explains how a simple integer setting in CrowCI is converted into an environment variable with a 'PLUGIN_' prefix. The integer value is serialized as a string.

```yaml
anInteger: 3
# Becomes PLUGIN_ANINT="3"
```

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

### Define Build Steps

Source: https://crowci.dev/4.5/usage/workflow-syntax

Defines a sequence of steps to be executed serially for building, testing, and deploying. Each step has a name, an image to run in, and a list of commands. If any step returns a non-zero exit code, the workflow terminates unless the step has `status: [failure]` set.

```yaml
steps:
  - name: backend
    image: <image>
    commands:
      - <command 1>
      - <command 2>
  - name: frontend
    image: <image>
    commands: |
      <command 1>


```

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

### Platform Conditions for CI/CD Steps

Source: https://crowci.dev/4.5/usage/workflow-syntax

Execute steps on specific operating systems and architectures. Supports exact matches and wildcard patterns for platform specifications. Not recommended for Kubernetes backend.

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

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

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

### Crow Agent Environment Variables for Internal Network Connection

Source: https://crowci.dev/4.5/installation

These environment variables are used to configure a Crow agent to connect to a Crow server over an internal network. They specify the server's address, the gRPC address, and the agent token for authentication. Ensure the agent token is created in the Crow server UI or API beforehand.

```bash
# address of the Crow server: private ip (e.g. 10.x.x.x) + port
CROW_SERVER: <private server ip>:8000
CROW_GRPC_ADDR: <private server ip>:9000
# agent token, previously created in Crow server
CROW_AGENT_SECRET: <token>
```

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

### Manage Crow CI Agent macOS launchd Service

Source: https://crowci.dev/4.5/installation/binary

This snippet details commands for managing the Crow CI agent service on macOS using `launchctl`. It includes operations to stop, restart, unload (remove), and check the status of the `crowci.agent` service. These commands are essential for service lifecycle management after initial setup.

```shell
# Stop the service
sudo launchctl kickstart -k system/crowci.agent

# Restart the service
sudo launchctl kickstart -kp system/crowci.agent

# Unload/remove the service
sudo launchctl bootout system /Library/LaunchDaemons/crowci.agent.plist

# Check service status
sudo launchctl print system/crowci.agent

```

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

### Install Ansible Collection

Source: https://crowci.dev/4.5/installation/ansible

Installs the 'devxy.cicd' Ansible collection which contains the CrowCI role. This can be done directly using ansible-galaxy or by specifying it in a requirements.yml file.

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

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

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

### Matrix Pipeline with Variable Image Tag

Source: https://crowci.dev/4.5/usage/pipelines

An example of a matrix pipeline where the image tag is a matrix variable. This allows building with different versions of a specified image.

```yaml
matrix:
  IMAGE:
    - golang:1.7
    - golang:1.8
    - golang:latest

steps:
  - name: build
    image: ${IMAGE}
    commands:
      - go build
      - go test
```

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

### Local Backend Plugin Execution

Source: https://crowci.dev/4.5/configuration/server

Demonstrates how to specify a plugin executable for the 'local' backend. The `image` field points to the binary, which can be found in the system's PATH or specified via an absolute path.

```yaml
steps:
  - name: build
    image: /usr/bin/tree
```

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

### Boolean Setting Conversion to Environment Variable (CrowCI)

Source: https://crowci.dev/4.5/plugins

Illustrates how a simple boolean setting in CrowCI is converted into an environment variable with a 'PLUGIN_' prefix. The boolean value is serialized as a string.

```yaml
some-bool: false
# Becomes PLUGIN_SOME_BOOL="false"
```

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

### Trigger Workflow on Push Event

Source: https://crowci.dev/4.5/usage/pipelines

Defines the event that triggers a workflow. At least one event trigger is mandatory. This example shows a workflow that executes on a 'push' event.

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

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

### Inject Sensitive Secrets via Kubernetes Secrets

Source: https://crowci.dev/4.5/installation/helm

Helm configuration to provide sensitive environment variables to server and agent pods by referencing Kubernetes secrets.

```yaml
extraSecretNamesForEnvFrom:
  - sensitive-secrets
```

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

### Generate Shell Script from Commands

Source: https://crowci.dev/4.5/usage/workflow-syntax

Illustrates the shell script generated internally from a list of commands, which is then executed as the container entrypoint. The `set -e` command ensures the script exits immediately if any command fails.

```shell
#!/bin/sh
set -e

go build
go test

```

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

### Configure Agent Affinity for Pod Distribution

Source: https://crowci.dev/4.5/installation/helm

Helm values to configure pod anti-affinity for agents, ensuring they are scheduled on different nodes. This increases agent resilience.

```yaml
affinity:
 podAntiAffinity:
   requiredDuringSchedulingIgnoredDuringExecution:
     - labelSelector:
         matchExpressions:
           - key: app.kubernetes.io/name
             operator: In
             values:
               - agent
       topologyKey: kubernetes.io/hostname
```

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

### Skip clone step in CrowCI workflow

Source: https://crowci.dev/4.5/usage/workflow-syntax

This YAML configuration demonstrates how to completely skip the automatic cloning step in a CrowCI workflow using `skip_clone: true`. This can save time, especially when using Kubernetes backends with RWX volumes, by avoiding the mount/umount operations across nodes.

```yaml
skip_clone: true
```

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

### Configure MySQL/MariaDB Database (Crow CI)

Source: https://crowci.dev/4.5/configuration/server

Sets the database driver to MySQL and provides the data source connection string. The `parseTime=true` parameter is important for Go MySQL driver compatibility. Check the go-sql-driver/mysql README for version requirements.

```shell
CROW_DATABASE_DRIVER=mysql
CROW_DATABASE_DATASOURCE=<user>:<pw>@tcp(0.0.0.0:3306)/<dbname>?parseTime=true
```

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

### Use Secrets in Commands with Escaping

Source: https://crowci.dev/4.5/usage/secrets

Shows how to use secrets directly within commands by escaping the environment variable reference with double dollar signs (`$$`). This ensures the variable is evaluated correctly before the workflow starts.

```yaml
steps:
  - name: docker
    image: docker
    commands:
      - echo $${TOKEN_ENV}
    environment:
      TOKEN_ENV:
        from_secret: secret_token
```

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

### Mount Host Directory (Docker) in CrowCI

Source: https://crowci.dev/4.5/usage/volumes

Demonstrates how to mount a directory from the host machine into a pipeline container using absolute paths. This is the standard method for the Docker backend. Ensure the 'volumes' security option is enabled.

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

```

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

### Configure CrowCI workspace base and path

Source: https://crowci.dev/4.5/usage/workflow-syntax

This YAML snippet defines the workspace for a CrowCI workflow, setting the base shared volume to '/go' and the working directory to 'src/github.com/octocat/hello-world'. This ensures source code and dependencies are persisted and shared across workflow steps.

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

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

### Define Workflow Dependencies

Source: https://crowci.dev/4.5/usage/pipelines

Specifies the execution order for steps or workflows. Steps within a workflow run sequentially by default, but 'depends_on' can enforce explicit ordering. Workflows with dependencies only start if the dependent ones complete successfully.

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

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