Using Plugins

Learn how to configure and use plugins effectively in your Crow CI pipelines.

Basic Usage

Plugins are defined as steps with an image and settings:

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

Settings

The settings key is the primary way to configure plugins. Each setting is converted to an environment variable with a PLUGIN_ prefix.

Simple Settings

Boolean, numeric, and string values become strings:

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

Naming Conventions

Setting names are transformed to uppercase with underscores:

Setting	Environment Variable
some-setting	PLUGIN_SOME_SETTING
someValue	PLUGIN_SOMEVALUE
nested_value	PLUGIN_NESTED_VALUE

Complex Settings

How a setting is encoded depends on its type:

Setting type	Encoding
Object (map)	JSON
Array containing objects or nested arrays	JSON
Array of plain values (strings, numbers, booleans)	Comma-separated

settings:
  targets:
    - production
    - staging
  complex:
    abc: 2
    list:
      - item1
      - item2

Results in:

• PLUGIN_TARGETS='production,staging'
• PLUGIN_COMPLEX='{"abc":2,"list":["item1","item2"]}'

targets is a top-level array of plain values, so it is comma-separated rather than JSON. The nested list sits inside an object, so it is encoded as part of that object’s JSON.

Caution

Comma-separated encoding has no escaping. A plain value that itself contains a comma cannot be distinguished from two separate values.

Lists Containing Commas

To pass values that contain commas, nest the array inside an object to have it encoded as JSON instead:

settings:
  files:
    paths:
      - 'file,with,commas.txt'
      - CHANGELOG.md

Results in PLUGIN_FILES='{"paths":["file,with,commas.txt","CHANGELOG.md"]}'.

The plugin must be written to accept this object form.

Secrets in Plugins

Use from_secret to inject sensitive values:

steps:
  - name: deploy
    image: codefloe.com/crow-plugins/docker-buildx
    settings:
      username:
        from_secret: docker_username
      password:
        from_secret: docker_password
      repo: myorg/myapp

Secret Filtering

For enhanced security, restrict secrets to specific plugins:

# In repository secrets configuration
secrets:
  - name: docker_password
    plugins_only: true
    allowed_plugins:
      - codefloe.com/crow-plugins/docker-buildx

See Secrets documentation for more details.

Privileged Plugins

Some plugins (like Docker builders) require privileged mode. This must be enabled by the server administrator.

steps:
  - name: build-image
    image: codefloe.com/crow-plugins/docker-buildx
    privileged: true  # Requires admin approval
    settings:
      repo: myorg/myapp

Caution

Only use privileged: true when absolutely necessary. Privileged containers have elevated system access.

Server Configuration

Administrators configure allowed privileged plugins:

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

Match types include:

• semver (default) - Match by major/minor version
• semver-range - Use semver constraint syntax
• exact - Match exact image tag
• regex - Match by regular expression

Conditional Plugin Execution

Use when conditions to control when plugins run:

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

Plugin Dependencies

Control execution order with depends_on:

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

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

Troubleshooting

Plugin Not Working

1. Check image availability - Ensure the plugin image exists and is accessible
2. Verify settings - Review plugin documentation for required settings
3. Check logs - Plugin output appears in step logs
4. Secrets - Ensure secrets are properly configured and accessible

Environment Variables Not Passed

Remember that environment: is not allowed for plugins in Crow. All configuration must use settings:.

# ❌ Wrong - environment not allowed for plugins
steps:
  - name: deploy
    image: some-plugin
    environment:
      MY_VAR: value

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