⚠️ Do not clone this repository directly!

Use formae plugin init to create your plugin. This command scaffolds a new plugin from this template with proper naming and configuration.

formae plugin init my-plugin

---

Setup Checklist

Remove this section and the warning above after completing setup.

After creating your plugin with formae plugin init, complete these steps:

• Update formae-plugin.pkl with your plugin metadata (name, namespace, description)
• Define your resource types in schema/pkl/*.pkl
• Implement CRUD operations in plugin.go
• Update test fixtures in testdata/*.pkl to use your resources
• Update this README (replace title, description, resources table, etc.)
• Set up local credentials for testing
• Run conformance tests locally: make conformance-test
• Configure CI credentials in .github/workflows/ci.yml (optional)
• Remove this checklist section and the warning box above

For detailed guidance, see the Plugin SDK Documentation.

---

Example Plugin for formae

TODO: Update title and description for your plugin

Example Formae plugin template - replace this with a description of what your plugin manages.

Installation

# Install the plugin
make install

Supported Resources

TODO: Document your supported resource types

Resource Type	Description
EXAMPLE::Service::Resource	Example resource (replace with your actual resources)

Configuration

Configure a target in your Forma file:

new formae.Target {
    label = "my-target"
    namespace = "EXAMPLE"  // TODO: Update with your namespace
    config = new Mapping {
        ["region"] = "us-east-1"
        // TODO: Add your provider-specific configuration
    }
}

Examples

See the examples/ directory for usage examples.

# Evaluate an example
formae eval examples/basic/main.pkl

# Apply resources
formae apply --mode reconcile --watch examples/basic/main.pkl

Development

Prerequisites

• Go 1.25+
• Pkl CLI
• Cloud provider credentials (for conformance testing)

Building

make build      # Build plugin binary
make test       # Run unit tests
make lint       # Run linter
make install    # Build + install locally

Local Testing

# Install plugin locally
make install

# Start formae agent
formae agent start

# Apply example resources
formae apply --mode reconcile --watch examples/basic/main.pkl

Conformance Testing

Conformance tests validate your plugin's CRUD lifecycle using the test fixtures in testdata/:

File	Purpose
resource.pkl	Initial resource creation
resource-update.pkl	In-place update (mutable fields)
resource-replace.pkl	Replacement (createOnly fields)

The test harness sets FORMAE_TEST_RUN_ID for unique resource naming between runs.

make conformance-test                  # Latest formae version
make conformance-test VERSION=0.80.0   # Specific version

The scripts/ci/clean-environment.sh script cleans up test resources. It runs before and after conformance tests and should be idempotent.

Licensing

Plugins are independent works and may be licensed under any license of the author’s choosing.

See the formae plugin policy: <https://docs.formae.io/plugin-sdk/