Skip to main content
Version: Current

Contribute a Configuration

Add a working configuration to the Configurations library through cradle-lang/cradle-lib. You import the implementation, generate and review its article, and open a source PR. After approval, automation prepares a separate website PR for publication.

:::info Start with a working module AI generates documentation only. It does not implement the configuration, render its templates, deploy machines or test its behavior. Verify the article against your files and document runtime results separately. :::

Before you start​

You need Git, Node.js 22 or newer, npm, a GitHub account, your implementation and an OpenAI-compatible LLM server for article generation. Include only files you have permission to redistribute.

Run commands from the cradle-lib repository root. Modules belong under configs/<name>/. Prefer lowercase names such as linux-my-service; existing mixed-case names retain their exact spelling in config() and source paths.

Contribution workflow​

Configuration module files
↓
Import with --generate-index
↓
Review the article and source PR
↓
Merge source PR and validate main
↓
Review and merge automatic website PR
↓
Pages publishes the configuration

1. Set up the repository​

Fork cradle-lib if you do not have write access. Replace YOUR-GITHUB-USERNAME; contributors with access can clone upstream instead.

git clone https://github.com/YOUR-GITHUB-USERNAME/cradle-lib.git
cd cradle-lib
git switch -c add-my-configuration
npm ci

For an existing checkout, update main before creating your contribution branch. TTPs use heuristics/ttp/ in the same repository; CVEs are authored separately in cradle-lib-cve.

Configure article generation once​

Create .env from .env.example if you do not already have one.

PowerShell​

if (!(Test-Path -LiteralPath .env)) {
Copy-Item -LiteralPath .env.example -Destination .env
}
notepad .env

Bash / Zsh​

if [ ! -f .env ]; then
cp .env.example .env
fi
nano .env

Configure your OpenAI-compatible Chat Completions endpoint, model and key:

SERVER="https://your-llm-server.example/v1"
REMOTE_LLM_MODEL="your-model-name"
REMOTE_LLM_API_KEY="your-key-here"

:::warning Credentials and module content Never commit .env or include credentials in module files. Selected text is sent to your configured server. Hidden and TOML files are excluded from model context; image and binary contents are not sent. Review reported omissions and truncation. :::

2. Prepare your source folder​

Keep the completed implementation and supporting documentation together:

MyConfiguration/
├── README.md
├── ansible/
│ └── linux-my-service.j2
└── files/
└── supporting-script.sh

The nonempty ansible/<name>.j2 template is required and must match the exact configuration name. files/ is optional. A README helps the generator understand implementation, requirements, parameters, verification and attribution.

Configurations do not require manifest.json. Their operating systems and dependencies must be documented explicitly; a configuration does not imply an instance OS in the same way a heuristic manifest can.

3. Import and generate the article​

Replace the name and source path with your own.

PowerShell​

npm run library:new -- configuration linux-my-service --from "C:\path\to\MyConfiguration" --generate-index

Bash / Zsh​

npm run library:new -- configuration linux-my-service --from "$HOME/Downloads/MyConfiguration" --generate-index

This copies your module into configs/linux-my-service/ and generates its index.md using the configuration template. A portable copy is included at library/_templates/configuration/index.md in cradle-lib. The exact configuration name is filled in automatically.

configs/linux-my-service/
├── index.md
├── README.md
├── ansible/
│ └── linux-my-service.j2
└── files/
└── supporting-script.sh

The original source folder is unchanged. Hidden files and caches are skipped; other files, including binary assets, are copied. Symbolic links and special files are rejected. Compare the imported folder with your source.

Existing destination modules are never overwritten. An authored source index.md is preserved even with --generate-index. Edit existing modules directly, and use index.md rather than index.mdx.

4. Review the article​

Edit configs/linux-my-service/index.md and verify its implementation, requirements, parameters, example, verification steps, attribution and licensing. Do not treat generated prose as evidence of a successful test.

---
title: My service configuration
config: linux-my-service
os: Linux
category: Networking
description: Describe what this configuration changes.
draft: true
---

Keep config identical to the module folder and the name in config("linux-my-service"). Set os to Linux, Windows, Cross-platform or Unspecified, and choose a meaningful category. These article fields describe the module; they do not configure the guest OS or install dependencies automatically. Do not add id, slug, framework or identifier.

Generated articles always start with draft: true. Set draft: false when the article is ready for publication. A GitHub draft PR and this article flag are separate controls.

You do not need to enter sourceUrl or a GitHub module link. Automation generates a configs/<name>/ link pinned to the validated source commit and rewrites relative article links to supporting files at the same commit.

The website receives index.md and the module-folder link, with tracking metadata. Ansible templates, scripts and binary assets remain in cradle-lib.

5. Open a draft source PR​

Before submitting, confirm that:

  • The folder, article config field and template name match exactly.
  • All required implementation files and assets are included.
  • OS, dependencies, parameters and backend requirements are accurate.
  • Verification claims have evidence; unknown details are marked clearly.
  • Attribution, licensing, links and publication status are complete.
  • No credentials, .env, dependencies or export bundles are staged.
git add configs/linux-my-service/
git diff --cached
git status --short
git commit -m "Add configuration module and documentation"
git push -u origin add-my-configuration

Open a draft PR against cradle-lang/cradle-lib → main. Describe the behavior, included files, supported systems, checks actually run and known limitations. Mark it ready for review when complete.

CI validates configuration names, required templates, article metadata, local links and exported Markdown, and runs import/generation/export tests. TTP validation remains available in the same repository. Contributors do not need to run export or synchronization commands manually.

:::info Validation is not runtime testing These checks do not render or execute provisioning templates, validate every referenced variable or remote download, or deploy the configuration. Record separate runtime tests and their environment in the article and PR. :::

6. What happens after submission​

StageWhat happens
Source PRValidate the implementation and article; maintainers review the contribution.
Source mergeSuccessful full main validation exports articles and notifies the website.
Website PRImport articles and module links, run website tests and a production build, then open or update a separate review PR.
Website merge and deploymentPages publishes articles with draft: false in the Configurations library.

A source merge alone does not publish a webpage. After deployment, inspect your configuration card, article and View on GitHub link. The example article route would be /library/configurations/linux-my-service. Existing configuration routes are preserved, including lowercase routes for mixed-case source names.

Troubleshooting​

ProblemWhat to check or do
The module already existsEdit the existing module. Imports never overwrite its folder.
Template validation failsCheck the exact folder name and nonempty ansible/<name>.j2.
Metadata validation failsCheck config, the allowed os values, a nonempty title/description/category and boolean draft.
Article generation failsCheck endpoint/model/API access. Copied files and the starter article are preserved.
An article was preservedThe source already contains index.md; review and edit it.
A local link failsLink an existing file or directory inside the configuration module, with the correct spelling and case.
The card does not appearCheck draft: false, source validation, website PR merge and Pages deployment.

Maintainer recovery and automation details are documented in docs/automation.md in the cradle-lib repository.