From 2c081f0067fe233fcacdbcc62a4de565336c2ce6 Mon Sep 17 00:00:00 2001 From: Continue Agent Date: Thu, 9 Oct 2025 16:07:08 +0000 Subject: [PATCH] docs: clarify secrets vs inputs syntax usage Add info blocks to documentation explaining when to use secrets. vs inputs. syntax: - Recommend secrets. as the default for most use cases - Explain inputs. provides flexibility for reusable blocks - Reference GitHub Actions pattern for clarity This addresses user confusion around the two syntaxes and provides clear guidance on when each should be used. Generated with [Continue](https://continue.dev) Co-authored-by: Ting-Wai To Co-authored-by: Continue --- docs/guides/configuring-models-rules-tools.mdx | 13 +++++++++++++ docs/hub/blocks/create-a-block.mdx | 10 ++++++++++ 2 files changed, 23 insertions(+) diff --git a/docs/guides/configuring-models-rules-tools.mdx b/docs/guides/configuring-models-rules-tools.mdx index 2a2d3d87e85..b31e6e938be 100644 --- a/docs/guides/configuring-models-rules-tools.mdx +++ b/docs/guides/configuring-models-rules-tools.mdx @@ -107,6 +107,19 @@ When configuring a local model or MCP server, you can use the same mustache nota + +**When to use `secrets.` vs `inputs.`** + +For most use cases, **use `${{ secrets.SECRET_NAME }}`** directly in your configuration. This is the recommended approach for both personal and organizational workflows. + +Use `${{ inputs.INPUT_NAME }}` only when you need flexibility to: +- Allow users to customize which secret a block uses without editing the block itself +- Change the secret name without modifying the block configuration +- Create reusable blocks where different users may have differently-named secrets + +This pattern is inspired by GitHub Actions, where inputs provide an abstraction layer between block definitions and user-specific values. For most scenarios, directly referencing `secrets.` keeps configuration simpler and more straightforward. + + ## Overriding Properties You can directly override properties using the `override` syntax: diff --git a/docs/hub/blocks/create-a-block.mdx b/docs/hub/blocks/create-a-block.mdx index 3b59267a8b2..af3199ab906 100644 --- a/docs/hub/blocks/create-a-block.mdx +++ b/docs/hub/blocks/create-a-block.mdx @@ -27,3 +27,13 @@ After filling out information on the block, you will want to create a block foll ### Block Inputs Blocks can receive values, including secrets, as inputs through templating. For values that the user of the block needs to set, you can use template variables (e.g. `${{ inputs.API_KEY}}`). Then, the user can set `API_KEY: ${{ secrets.MY_API_KEY }}` in the `with` clause of their agent. + + +**Choosing between `secrets.` and `inputs.`** + +When creating blocks for the hub: +- Use `${{ inputs.INPUT_NAME }}` in your block definition when you want users to be able to customize which secret is used +- Users will then map their own secrets using `${{ secrets.SECRET_NAME }}` in the `with` clause + +For personal or single-use configurations, you can skip the inputs layer and reference `${{ secrets.SECRET_NAME }}` directly in your block. +