From 57420057bce3e1f63003ce715ea96ce3601cbe96 Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Tue, 15 Apr 2025 12:42:02 +0200 Subject: [PATCH 01/11] docs: adding some life to the software template docs Signed-off-by: Peter Macdonald --- .../software-templates/configuration.md | 5 +- .../software-templates/input-examples.md | 55 +++++++++++++++---- .../software-templates/writing-templates.md | 3 +- 3 files changed, 48 insertions(+), 15 deletions(-) diff --git a/docs/features/software-templates/configuration.md b/docs/features/software-templates/configuration.md index 571f1150d0..a692335ffe 100644 --- a/docs/features/software-templates/configuration.md +++ b/docs/features/software-templates/configuration.md @@ -78,11 +78,11 @@ Once you have more than a few software templates you may want to customize your accomplish this by creating `groups` and passing them to your `ScaffolderPage` like below -``` +```tsx entity?.metadata?.tags?.includes('recommended') ?? false, }, @@ -96,6 +96,7 @@ top of the page above any other templates not filtered by this group or others. You can also further customize groups by passing in a `titleComponent` instead of a `title` which will be a component to use as the header instead of just the default `ContentHeader` with the `title` set as it's value. + ![Grouped Templates](../../assets/software-templates/grouped-templates.png) There is also an option to hide some templates. diff --git a/docs/features/software-templates/input-examples.md b/docs/features/software-templates/input-examples.md index bb4ecde946..84cfec28ed 100644 --- a/docs/features/software-templates/input-examples.md +++ b/docs/features/software-templates/input-examples.md @@ -12,6 +12,8 @@ It is important to remember that all examples are based on [react-jsonschema-for ### Simple input with basic validations +We can use a `pattern` to validate the input. The `pattern` is a regular expression that the input must match. + ```yaml parameters: - title: Fill in some steps @@ -28,6 +30,8 @@ parameters: #### Custom validation error message +This example shows how to customize the error message shown when the `pattern` validation fails. + ```yaml parameters: - title: Fill in some steps @@ -47,6 +51,8 @@ parameters: ### Multi line text input +If you need to insert a multi-line string, you can use the `ui:widget: textarea` option. This will create a text area input instead of a single line input. + ```yaml parameters: - title: Fill in some steps @@ -74,6 +80,8 @@ parameters: ### Array with custom titles +In the example below the user will see the the `enumNames` instead of the `enum` values, making it easier to read. + ```yaml parameters: - title: Fill in some steps @@ -103,6 +111,8 @@ parameters: ### A multiple choices list +This is a simple multiple choice list. + ```yaml parameters: - title: Fill in some steps @@ -122,6 +132,8 @@ parameters: ### Array with another types +In the example below, it will create an array of custom objects. Once you add one, you will see an object where each one contains 3 fields, "How are you?", "Is it sunny?" and "Anything else?". + ```yaml parameters: - title: Fill in some steps @@ -138,19 +150,19 @@ parameters: type: object properties: array: - title: Array string with default value + title: How are you? type: string - default: value3 + default: good enum: - - value1 - - value2 - - value3 + - good + - okay + - great flag: - title: Boolean flag + title: Is it sunny? type: boolean ui:widget: radio someInput: - title: Simple text input + title: Anything else? type: string ``` @@ -158,6 +170,8 @@ parameters: ### Boolean +This adds a simple checkbox to the form. The value will be `true` or `false`. + ```yaml parameters: - title: Fill in some steps @@ -169,6 +183,8 @@ parameters: ### Boolean Yes or No options +This example shows how to use a radio button instead of a checkbox with `Yes` or `No` options. + ```yaml parameters: - title: Fill in some steps @@ -181,6 +197,8 @@ parameters: ### Boolean multiple options +You can create multiple checkboxes with different options. The example below shows how to create a list of features that can be enabled or disabled for example. + ```yaml parameters: - title: Fill in some steps @@ -200,6 +218,8 @@ parameters: ## Markdown text blocks +Its possible to render markdown text blocks in the form. This is useful to add some help text or instructions for the user. + ```yaml parameters: - title: Fill in some steps @@ -217,7 +237,7 @@ parameters: ## Use parameters as condition in steps -Conditions use Javascript equality operators. +Its possible to conditionally run steps based on the value of a parameter. In the example below, we trigger the steps depending on the value of the `environment` parameter. ```yaml - name: Only development environments @@ -241,6 +261,8 @@ Conditions use Javascript equality operators. ## Use parameters as conditional for fields +Its also possible to conditionally show fields based on the value of a parameter. In the example below, we show the `lastName` field only if the `includeName` parameter is set to `true`. + ```yaml parameters: - title: Fill in some steps @@ -269,6 +291,9 @@ parameters: ### Multiple conditional fields with custom ordering +In this example, we show how to conditionally show multiple fields based on the value of a parameter. The `ui:order` property is used to control the order of the fields in the form. +In this case, we show the `lastName` and `address` fields only if the `includeName` and `includeAddress` parameters are set to `true`. + ```yaml parameters: - title: Fill in some steps @@ -349,12 +374,16 @@ Testing of this functionality is not yet supported using _create/edit_. In addit ::: +Its possible to use placeholders to reference remote files. This is useful when you have some standard parameters or actions that you want to reuse across multiple templates. + ### template.yaml +In our template, we use the `$yaml` placeholder to reference the `parameters.yaml` and `action.yaml` files. The `parameters.yaml` file contains some parameters that we want to use in our template, and the `action.yaml` file contains the action that we want to run. + ```yaml spec: parameters: - - $yaml: https://github.com/example/path/to/example.yaml + - $yaml: https://github.com/example/path/to/parameters.yaml # This would become the parameters as referenced in the parameters.yaml file - title: Fill in some steps properties: path: @@ -362,7 +391,7 @@ spec: type: string steps: - - $yaml: https://github.com/example/path/to/action.yaml + - $yaml: https://github.com/example/path/to/action.yaml # This would become the publish action as referenced in the action.yaml file - id: fetch name: Fetch template @@ -371,7 +400,9 @@ spec: url: ${{ parameters.path if parameters.path else '/root' }} ``` -### example.yaml +### parameters.yaml + +The `url` parameter will be added to the template. ```yaml title: Provide simple information @@ -385,6 +416,8 @@ properties: ### action.yaml +The `publish:github` action will be included in our template. + ```yaml id: publish name: Publish files diff --git a/docs/features/software-templates/writing-templates.md b/docs/features/software-templates/writing-templates.md index bc2847a81b..4f8691e948 100644 --- a/docs/features/software-templates/writing-templates.md +++ b/docs/features/software-templates/writing-templates.md @@ -4,8 +4,7 @@ title: Writing Templates description: Details around creating your own custom Software Templates --- -Templates are stored in the **Software Catalog** under a kind `Template`. You -can create your own templates with a small `yaml` definition which describes the +You can create your own templates with a small `yaml` definition which describes the template and its metadata, along with some input variables that your template will need, and then a list of actions which are then executed by the scaffolding service. From 6b7079be931939eceaec7eed21ab0c68d416737c Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Tue, 15 Apr 2025 13:51:24 +0200 Subject: [PATCH 02/11] docs: remove some redundant parts, add urls to the modules Signed-off-by: Peter Macdonald --- .../software-templates/builtin-actions.md | 21 +++++++------------ 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/docs/features/software-templates/builtin-actions.md b/docs/features/software-templates/builtin-actions.md index bf6875764e..75dee9d2a1 100644 --- a/docs/features/software-templates/builtin-actions.md +++ b/docs/features/software-templates/builtin-actions.md @@ -12,13 +12,13 @@ git repository. There are also several modules available for various SCM tools: -- Azure DevOps: `@backstage/plugin-scaffolder-backend-module-azure` -- Bitbucket Cloud: `@backstage/plugin-scaffolder-backend-module-bitbucket-cloud` -- Bitbucket Server: `@backstage/plugin-scaffolder-backend-module-bitbucket-server` -- Gerrit: `@backstage/plugin-scaffolder-backend-module-gerrit` -- Gitea: `@backstage/plugin-scaffolder-backend-module-gitea` -- GitHub: `@backstage/plugin-scaffolder-backend-module-github` -- GitLab: `@backstage/plugin-scaffolder-backend-module-gitlab` +- [Azure DevOps](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-azure): `@backstage/plugin-scaffolder-backend-module-azure` +- [Bitbucket Cloud](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-bitbucket-cloud): `@backstage/plugin-scaffolder-backend-module-bitbucket-cloud` +- [Bitbucket Server](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-bitbucket-server): `@backstage/plugin-scaffolder-backend-module-bitbucket-server` +- [Gerrit](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-gerrit): `@backstage/plugin-scaffolder-backend-module-gerrit` +- [Gitea](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-gitea): `@backstage/plugin-scaffolder-backend-module-gitea` +- [GitHub](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-github): `@backstage/plugin-scaffolder-backend-module-github` +- [GitLab](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-gitlab): `@backstage/plugin-scaffolder-backend-module-gitlab` ## Installing Action Modules @@ -37,7 +37,6 @@ const backend = createBackend(); backend.add(import('@backstage/plugin-app-backend')); -// catalog plugin backend.add(import('@backstage/plugin-catalog-backend')); backend.add( import('@backstage/plugin-catalog-backend-module-scaffolder-entity-model'), @@ -51,12 +50,6 @@ backend.add(import('@backstage/plugin-scaffolder-backend-module-github')); backend.start(); ``` -:::note Note - -This is a simplified example of what your backend may look like, you may have more code in here then this. - -::: - ## Listing Actions A list of all registered actions can be found under `/create/actions`. For local From ac82ed9c6364789c657c5352ea6b16fb0f477555 Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Tue, 15 Apr 2025 14:00:36 +0200 Subject: [PATCH 03/11] docs: small adjustments to custom actions section Signed-off-by: Peter Macdonald --- .../writing-custom-actions.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index dd7a5e60a1..17a8ff20e4 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/docs/features/software-templates/writing-custom-actions.md @@ -25,7 +25,7 @@ setup process, allowing you to focus on your actions' unique functionality. Start by using the `yarn backstage-cli new` command to generate a scaffolder module. This command sets up the necessary boilerplate code, providing a smooth start: -``` +```sh $ yarn backstage-cli new ? What do you want to create? plugin-common - A new isomorphic common plugin package @@ -34,8 +34,6 @@ $ yarn backstage-cli new > scaffolder-module - An module exporting custom actions for @backstage/plugin-scaffolder-backend ``` -You can find a [list](../../tooling/cli/03-commands.md) of all commands provided by the Backstage CLI. - When prompted, select the option to generate a scaffolder module. This creates a solid foundation for your custom action. Enter the name of the module you wish to create, and the CLI will generate the required files and directory structure. @@ -87,7 +85,7 @@ for reference. The `createTemplateAction` takes an object which specifies the following: -- `id` - A unique ID for your custom action. We encourage you to namespace these +- `id` - A **unique** ID for your custom action. We encourage you to namespace these in some way so that they won't collide with future built-in actions that we may ship with the `scaffolder-backend` plugin. - `description` - An optional field to describe the purpose of the action. This will populate in the `/create/actions` @@ -151,9 +149,6 @@ Also feel free to use your company name to namespace them if you prefer too, for Prefer to use `camelCase` over `snake_case` or `kebab-case` for these actions if possible, which leads to better reading and writing of template entity definitions. -> We're aware that there are some exceptions to this, but try to follow as close as possible. We'll be working on -> migrating these in the repository over time too. - ### Adding a TemplateExample A TemplateExample is a predefined structure that can be used to create custom actions in your software templates. It @@ -187,7 +182,9 @@ export const examples: TemplateExample[] = [ Add the example to the `createTemplateAction` under the object property `examples`: -`return createTemplateAction<{ contents: string; filename: string }>({id: 'acme:file:create', description: 'Create an Acme file', examples, ...};` +```ts +return createTemplateAction<{ contents: string; filename: string }>({id: 'acme:file:create', description: 'Create an Acme file', examples, ...}); +``` ### The context object @@ -275,9 +272,7 @@ env.registerInit({ ### Using Checkpoints in Custom Actions (Experimental) -Idempotent action could be achieved via the usage of checkpoints. - -Example: +Idempotent action could be achieved via the usage of checkpoints, for example: ```ts title="plugins/my-company-scaffolder-actions-plugin/src/vendor/my-custom-action.ts" const res = await ctx.checkpoint?.({ From b5d87f2f501ae0153b75302c6b925d64423b3dd8 Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Tue, 15 Apr 2025 14:02:01 +0200 Subject: [PATCH 04/11] docs: remove legacy backend part Signed-off-by: Peter Macdonald --- .../writing-custom-actions.md | 51 ------------------- 1 file changed, 51 deletions(-) diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index 17a8ff20e4..ca5959e72e 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/docs/features/software-templates/writing-custom-actions.md @@ -300,57 +300,6 @@ If you'll preserve the same key, and you'll try to restart the affected task, it The cached result will not match with the expected updated return type. By changing the key, you'll invalidate the cache of the checkpoint. -### Register Custom Actions with the Legacy Backend System - -Once you have your Custom Action ready for usage with the scaffolder, you'll -need to pass this into the `scaffolder-backend` `createRouter` function. You -should have something similar to the below in -`packages/backend/src/plugins/scaffolder.ts` - -```ts -return await createRouter({ - catalogClient, - logger: env.logger, - config: env.config, - database: env.database, - reader: env.reader, -}); -``` - -There's another property you can pass here, which is an array of `actions` which -will set the available actions that the scaffolder has access to. - -```ts -import { createBuiltinActions } from '@backstage/plugin-scaffolder-backend'; -import { ScmIntegrations } from '@backstage/integration'; -import { createNewFileAction } from './scaffolder/actions/custom'; - -export default async function createPlugin( - env: PluginEnvironment, -): Promise { - const catalogClient = new CatalogClient({ discoveryApi: env.discovery }); - const integrations = ScmIntegrations.fromConfig(env.config); - - const builtInActions = createBuiltinActions({ - integrations, - catalogClient, - config: env.config, - reader: env.reader, - }); - - const actions = [...builtInActions, createNewFileAction()]; - - return createRouter({ - actions, - catalogClient: catalogClient, - logger: env.logger, - config: env.config, - database: env.database, - reader: env.reader, - }); -} -``` - ## List of custom action packages Here is a list of Open Source custom actions that you can add to your Backstage From 141742b184983b6d12fc7c174453a4c122f8945e Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Tue, 15 Apr 2025 14:14:39 +0200 Subject: [PATCH 05/11] docs: move around some of the contributed actions and available actions Signed-off-by: Peter Macdonald --- contrib/scaffolder/custom-action-packages.md | 19 ++++++++++++++ .../software-templates/builtin-actions.md | 6 ++++- .../writing-custom-actions.md | 25 ++----------------- 3 files changed, 26 insertions(+), 24 deletions(-) create mode 100644 contrib/scaffolder/custom-action-packages.md diff --git a/contrib/scaffolder/custom-action-packages.md b/contrib/scaffolder/custom-action-packages.md new file mode 100644 index 0000000000..d82221ae1e --- /dev/null +++ b/contrib/scaffolder/custom-action-packages.md @@ -0,0 +1,19 @@ +# List of custom action packages + +Here is a list of Open Source custom actions that you can add to your Backstage +scaffolder backend! + +| Name | Package | Owner | +| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| HTTP requests | [scaffolder-backend-module-http-request](https://www.npmjs.com/package/@roadiehq/scaffolder-backend-module-http-request) | [Roadie](https://roadie.io) | +| Utility actions | [scaffolder-backend-module-utils](https://www.npmjs.com/package/@roadiehq/scaffolder-backend-module-utils) | [Roadie](https://roadie.io) | +| AWS cli actions | [scaffolder-backend-module-aws](https://www.npmjs.com/package/@roadiehq/scaffolder-backend-module-aws) | [Roadie](https://roadie.io) | +| Scaffolder .NET Actions | [plugin-scaffolder-dotnet-backend](https://www.npmjs.com/package/@plusultra/plugin-scaffolder-dotnet-backend) | [Alef Carlos](https://github.com/alefcarlos) | +| Scaffolder Git Actions | [plugin-scaffolder-git-actions](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-git-actions) | [Drew Hill](https://github.com/arhill05) | +| Azure Pipeline Actions | [scaffolder-backend-module-azure-pipelines](https://www.npmjs.com/package/@parfuemerie-douglas/scaffolder-backend-module-azure-pipelines) | [Parfümerie Douglas](https://github.com/Parfuemerie-Douglas) | +| Azure Repository Actions | [scaffolder-backend-module-azure-repositories](https://www.npmjs.com/package/@parfuemerie-douglas/scaffolder-backend-module-azure-repositories) | [Parfümerie Douglas](https://github.com/Parfuemerie-Douglas) | +| Snyk Import Project | [plugin-scaffolder-backend-module-snyk](https://www.npmjs.com/package/@ma11hewthomas/plugin-scaffolder-backend-module-snyk) | [Matthew Thomas](https://github.com/Ma11hewThomas) | +| JSON Merge Actions | [plugin-scaffolder-json-merge-actions](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-json-merge-actions) | [Drew Hill](https://github.com/arhill05) | +| NPM Actions | [plugin-scaffolder-npm-actions](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-npm-actions) | [Drew Hill](https://github.com/arhill05) | +| Slack Actions | [plugin-scaffolder-backend-module-slack](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-backend-module-slack) | [Drew Hill](https://github.com/arhill05) | +| Microsoft Teams Actions | [plugin-scaffolder-backend-module-ms-teams](https://www.npmjs.com/package/@grvpandey11/backstage-plugin-scaffolder-backend-module-ms-teams) | [Gaurav Pandey](https://github.com/grvpandey11) | diff --git a/docs/features/software-templates/builtin-actions.md b/docs/features/software-templates/builtin-actions.md index 75dee9d2a1..d732bd8a27 100644 --- a/docs/features/software-templates/builtin-actions.md +++ b/docs/features/software-templates/builtin-actions.md @@ -10,7 +10,7 @@ git repository. ## Action Modules -There are also several modules available for various SCM tools: +There are several action modules that are available to be added: - [Azure DevOps](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-azure): `@backstage/plugin-scaffolder-backend-module-azure` - [Bitbucket Cloud](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-bitbucket-cloud): `@backstage/plugin-scaffolder-backend-module-bitbucket-cloud` @@ -19,6 +19,10 @@ There are also several modules available for various SCM tools: - [Gitea](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-gitea): `@backstage/plugin-scaffolder-backend-module-gitea` - [GitHub](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-github): `@backstage/plugin-scaffolder-backend-module-github` - [GitLab](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-gitlab): `@backstage/plugin-scaffolder-backend-module-gitlab` +- [Rails](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-rails): `@backstage/plugin-scaffolder-backend-module-rails` +- [Yeoman](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-yeoman): `@backstage/plugin-scaffolder-backend-module-yeoman` +- [Sentry](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-sentry): `@backstage/plugin-scaffolder-backend-module-sentry` +- [Cookiecutter](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-cookiecutter): `@backstage/plugin-scaffolder-backend-module-cookiecutter` ## Installing Action Modules diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index ca5959e72e..8987f9af40 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/docs/features/software-templates/writing-custom-actions.md @@ -300,27 +300,6 @@ If you'll preserve the same key, and you'll try to restart the affected task, it The cached result will not match with the expected updated return type. By changing the key, you'll invalidate the cache of the checkpoint. -## List of custom action packages +## Contributed Community Actions -Here is a list of Open Source custom actions that you can add to your Backstage -scaffolder backend: - -| Name | Package | Owner | -| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -| Yeoman | [plugin-scaffolder-backend-module-yeoman](https://www.npmjs.com/package/@backstage/plugin-scaffolder-backend-module-yeoman) | [Backstage](https://backstage.io) | -| Cookiecutter | [plugin-scaffolder-backend-module-cookiecutter](https://www.npmjs.com/package/@backstage/plugin-scaffolder-backend-module-cookiecutter) | [Backstage](https://backstage.io) | -| Rails | [plugin-scaffolder-backend-module-rails](https://www.npmjs.com/package/@backstage/plugin-scaffolder-backend-module-rails) | [Backstage](https://backstage.io) | -| HTTP requests | [scaffolder-backend-module-http-request](https://www.npmjs.com/package/@roadiehq/scaffolder-backend-module-http-request) | [Roadie](https://roadie.io) | -| Utility actions | [scaffolder-backend-module-utils](https://www.npmjs.com/package/@roadiehq/scaffolder-backend-module-utils) | [Roadie](https://roadie.io) | -| AWS cli actions | [scaffolder-backend-module-aws](https://www.npmjs.com/package/@roadiehq/scaffolder-backend-module-aws) | [Roadie](https://roadie.io) | -| Scaffolder .NET Actions | [plugin-scaffolder-dotnet-backend](https://www.npmjs.com/package/@plusultra/plugin-scaffolder-dotnet-backend) | [Alef Carlos](https://github.com/alefcarlos) | -| Scaffolder Git Actions | [plugin-scaffolder-git-actions](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-git-actions) | [Drew Hill](https://github.com/arhill05) | -| Azure Pipeline Actions | [scaffolder-backend-module-azure-pipelines](https://www.npmjs.com/package/@parfuemerie-douglas/scaffolder-backend-module-azure-pipelines) | [Parfümerie Douglas](https://github.com/Parfuemerie-Douglas) | -| Azure Repository Actions | [scaffolder-backend-module-azure-repositories](https://www.npmjs.com/package/@parfuemerie-douglas/scaffolder-backend-module-azure-repositories) | [Parfümerie Douglas](https://github.com/Parfuemerie-Douglas) | -| Snyk Import Project | [plugin-scaffolder-backend-module-snyk](https://www.npmjs.com/package/@ma11hewthomas/plugin-scaffolder-backend-module-snyk) | [Matthew Thomas](https://github.com/Ma11hewThomas) | -| JSON Merge Actions | [plugin-scaffolder-json-merge-actions](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-json-merge-actions) | [Drew Hill](https://github.com/arhill05) | -| NPM Actions | [plugin-scaffolder-npm-actions](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-npm-actions) | [Drew Hill](https://github.com/arhill05) | -| Slack Actions | [plugin-scaffolder-backend-module-slack](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-backend-module-slack) | [Drew Hill](https://github.com/arhill05) | -| Microsoft Teams Actions | [plugin-scaffolder-backend-module-ms-teams](https://www.npmjs.com/package/@grvpandey11/backstage-plugin-scaffolder-backend-module-ms-teams) | [Gaurav Pandey](https://github.com/grvpandey11) | - -Have fun! 🚀 +You can find a list of community-contributed actions here in our [contrib](https://github.com/backstage/backstage/blob/master/contrib/scaffolder/custom-action-packages.md) docs! From aebc6b7119e0b1cd49ec19c9372fe27db013915e Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Tue, 15 Apr 2025 14:17:02 +0200 Subject: [PATCH 06/11] docs: mention community plugins repo Signed-off-by: Peter Macdonald --- contrib/scaffolder/custom-action-packages.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/contrib/scaffolder/custom-action-packages.md b/contrib/scaffolder/custom-action-packages.md index d82221ae1e..d3b634bff5 100644 --- a/contrib/scaffolder/custom-action-packages.md +++ b/contrib/scaffolder/custom-action-packages.md @@ -1,7 +1,6 @@ # List of custom action packages -Here is a list of Open Source custom actions that you can add to your Backstage -scaffolder backend! +Here is a list of Open Source custom actions that you can add to your Backstage scaffolder backend! | Name | Package | Owner | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | @@ -17,3 +16,5 @@ scaffolder backend! | NPM Actions | [plugin-scaffolder-npm-actions](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-npm-actions) | [Drew Hill](https://github.com/arhill05) | | Slack Actions | [plugin-scaffolder-backend-module-slack](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-backend-module-slack) | [Drew Hill](https://github.com/arhill05) | | Microsoft Teams Actions | [plugin-scaffolder-backend-module-ms-teams](https://www.npmjs.com/package/@grvpandey11/backstage-plugin-scaffolder-backend-module-ms-teams) | [Gaurav Pandey](https://github.com/grvpandey11) | + +You may also want to check out the [Community Plugins Repo](https://github.com/backstage/community-plugins) for more! From 0592917347354e83059a52101d7ae1a83b6821e3 Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Tue, 15 Apr 2025 14:42:28 +0200 Subject: [PATCH 07/11] docs: update contributed actions to refer to plugins directory and community repo instead Signed-off-by: Peter Macdonald --- contrib/scaffolder/custom-action-packages.md | 20 ------------------- .../writing-custom-actions.md | 5 ++++- 2 files changed, 4 insertions(+), 21 deletions(-) delete mode 100644 contrib/scaffolder/custom-action-packages.md diff --git a/contrib/scaffolder/custom-action-packages.md b/contrib/scaffolder/custom-action-packages.md deleted file mode 100644 index d3b634bff5..0000000000 --- a/contrib/scaffolder/custom-action-packages.md +++ /dev/null @@ -1,20 +0,0 @@ -# List of custom action packages - -Here is a list of Open Source custom actions that you can add to your Backstage scaffolder backend! - -| Name | Package | Owner | -| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -| HTTP requests | [scaffolder-backend-module-http-request](https://www.npmjs.com/package/@roadiehq/scaffolder-backend-module-http-request) | [Roadie](https://roadie.io) | -| Utility actions | [scaffolder-backend-module-utils](https://www.npmjs.com/package/@roadiehq/scaffolder-backend-module-utils) | [Roadie](https://roadie.io) | -| AWS cli actions | [scaffolder-backend-module-aws](https://www.npmjs.com/package/@roadiehq/scaffolder-backend-module-aws) | [Roadie](https://roadie.io) | -| Scaffolder .NET Actions | [plugin-scaffolder-dotnet-backend](https://www.npmjs.com/package/@plusultra/plugin-scaffolder-dotnet-backend) | [Alef Carlos](https://github.com/alefcarlos) | -| Scaffolder Git Actions | [plugin-scaffolder-git-actions](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-git-actions) | [Drew Hill](https://github.com/arhill05) | -| Azure Pipeline Actions | [scaffolder-backend-module-azure-pipelines](https://www.npmjs.com/package/@parfuemerie-douglas/scaffolder-backend-module-azure-pipelines) | [Parfümerie Douglas](https://github.com/Parfuemerie-Douglas) | -| Azure Repository Actions | [scaffolder-backend-module-azure-repositories](https://www.npmjs.com/package/@parfuemerie-douglas/scaffolder-backend-module-azure-repositories) | [Parfümerie Douglas](https://github.com/Parfuemerie-Douglas) | -| Snyk Import Project | [plugin-scaffolder-backend-module-snyk](https://www.npmjs.com/package/@ma11hewthomas/plugin-scaffolder-backend-module-snyk) | [Matthew Thomas](https://github.com/Ma11hewThomas) | -| JSON Merge Actions | [plugin-scaffolder-json-merge-actions](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-json-merge-actions) | [Drew Hill](https://github.com/arhill05) | -| NPM Actions | [plugin-scaffolder-npm-actions](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-npm-actions) | [Drew Hill](https://github.com/arhill05) | -| Slack Actions | [plugin-scaffolder-backend-module-slack](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-backend-module-slack) | [Drew Hill](https://github.com/arhill05) | -| Microsoft Teams Actions | [plugin-scaffolder-backend-module-ms-teams](https://www.npmjs.com/package/@grvpandey11/backstage-plugin-scaffolder-backend-module-ms-teams) | [Gaurav Pandey](https://github.com/grvpandey11) | - -You may also want to check out the [Community Plugins Repo](https://github.com/backstage/community-plugins) for more! diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index 8987f9af40..163df094a1 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/docs/features/software-templates/writing-custom-actions.md @@ -302,4 +302,7 @@ By changing the key, you'll invalidate the cache of the checkpoint. ## Contributed Community Actions -You can find a list of community-contributed actions here in our [contrib](https://github.com/backstage/backstage/blob/master/contrib/scaffolder/custom-action-packages.md) docs! +You can find a list of community-contributed and open-source actions by: + +- Going to the [Backstage Plugin Directory](https://backstage.io/plugins/) and filter by `scaffolder`! +- Checking out the [Community Plugins Repo](https://github.com/backstage/community-plugins)! From a182209fadb38b8b8cf3cd874e36d4160dd80d6e Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Tue, 15 Apr 2025 14:51:06 +0200 Subject: [PATCH 08/11] docs: not the the, but the Signed-off-by: Peter Macdonald --- docs/features/software-templates/input-examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/software-templates/input-examples.md b/docs/features/software-templates/input-examples.md index 84cfec28ed..f278351255 100644 --- a/docs/features/software-templates/input-examples.md +++ b/docs/features/software-templates/input-examples.md @@ -80,7 +80,7 @@ parameters: ### Array with custom titles -In the example below the user will see the the `enumNames` instead of the `enum` values, making it easier to read. +In the example below the user will see the `enumNames` instead of the `enum` values, making it easier to read. ```yaml parameters: From 247bd4fe219eefec321c336e9920c398565748e5 Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Wed, 30 Apr 2025 18:16:09 +0200 Subject: [PATCH 09/11] fix: update createTemplateAction example Signed-off-by: Peter Macdonald --- .../software-templates/writing-custom-actions.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index 163df094a1..51500f1c19 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/docs/features/software-templates/writing-custom-actions.md @@ -183,7 +183,19 @@ export const examples: TemplateExample[] = [ Add the example to the `createTemplateAction` under the object property `examples`: ```ts -return createTemplateAction<{ contents: string; filename: string }>({id: 'acme:file:create', description: 'Create an Acme file', examples, ...}); +return createTemplateAction({ + id: 'acme:file:create', + description: 'Create an Acme file', + schema: { + input: { + contents: d => d.string().describe('The contents of the file'), + filename: d => + d.string().describe('The filename of the file that will be created'), + }, + }, + examples: examples, + // ...rest of the action configuration +}); ``` ### The context object From f9ebd0392e7cd69fc8c408e51858e2d2bc51fcf3 Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Wed, 30 Apr 2025 18:19:50 +0200 Subject: [PATCH 10/11] fix: small tweak Signed-off-by: Peter Macdonald --- docs/features/software-templates/writing-custom-actions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index 51500f1c19..d3a6dffead 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/docs/features/software-templates/writing-custom-actions.md @@ -193,7 +193,7 @@ return createTemplateAction({ d.string().describe('The filename of the file that will be created'), }, }, - examples: examples, + examples, // ...rest of the action configuration }); ``` From 490a376407981eda0a197b77a00dbcee1f498db5 Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Wed, 30 Apr 2025 18:22:25 +0200 Subject: [PATCH 11/11] fix: another small tweak Signed-off-by: Peter Macdonald --- docs/features/software-templates/writing-custom-actions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index d3a6dffead..9a502d7195 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/docs/features/software-templates/writing-custom-actions.md @@ -180,7 +180,7 @@ export const examples: TemplateExample[] = [ ]; ``` -Add the example to the `createTemplateAction` under the object property `examples`: +Add the example to `createTemplateAction` by including the `examples` property: ```ts return createTemplateAction({