diff --git a/.changeset/many-spoons-join.md b/.changeset/many-spoons-join.md new file mode 100644 index 0000000000..55b59e0518 --- /dev/null +++ b/.changeset/many-spoons-join.md @@ -0,0 +1,9 @@ +--- +'@backstage/plugin-scaffolder-backend': patch +--- + +- **DEPRECATED** - The `containerRunner` option passed to `createBuiltinActions` has now been deprecated. + +- **DEPRECATED** - The `createFetchCookiecutterAction` export has also been deprecated and will soon disappear from this plugin. + +The `fetch:cookiecutter` action will soon be removed from the default list of actions that are provided out of the box from the scaffolder plugin. It will still be supported, and maintained by the community, so you can install the package (`@backstage/plugin-scaffolder-backend-module-cookiecutter`) and pass it in as a custom action. Or you can migrate your templates to use [`fetch:template`](https://backstage.io/docs/features/software-templates/builtin-actions#migrating-from-fetchcookiecutter-to-fetchtemplate) with the `cookiecutterCompat` option. diff --git a/plugins/scaffolder-backend/api-report.md b/plugins/scaffolder-backend/api-report.md index c0ff3b3f2b..aea6689183 100644 --- a/plugins/scaffolder-backend/api-report.md +++ b/plugins/scaffolder-backend/api-report.md @@ -53,17 +53,26 @@ export type ActionContext = { // @public @deprecated export type CompletedTaskState = TaskCompletionState; -// Warning: (ae-missing-release-tag) "createBuiltinActions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const createBuiltinActions: (options: { - reader: UrlReader; - integrations: ScmIntegrations; - catalogClient: CatalogApi; - containerRunner?: ContainerRunner; - config: Config; +// @public +export const createBuiltinActions: ( + options: CreateBuiltInActionsOptions, +) => TemplateAction[]; + +// @public +export interface CreateBuiltInActionsOptions { + // (undocumented) additionalTemplateFilters?: Record; -}) => TemplateAction[]; + // (undocumented) + catalogClient: CatalogApi; + // (undocumented) + config: Config; + // @deprecated (undocumented) + containerRunner?: ContainerRunner; + // (undocumented) + integrations: ScmIntegrations; + // (undocumented) + reader: UrlReader; +} // Warning: (ae-missing-release-tag) "createCatalogRegisterAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -356,9 +365,7 @@ export class DatabaseTaskStore implements TaskStore { // @public @deprecated export type DispatchResult = TaskBrokerDispatchResult; -// Warning: (ae-missing-release-tag) "fetchContents" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export function fetchContents({ reader, integrations, @@ -369,7 +376,7 @@ export function fetchContents({ reader: UrlReader; integrations: ScmIntegrations; baseUrl?: string; - fetchUrl?: JsonValue; + fetchUrl?: string; outputPath: string; }): Promise; @@ -487,7 +494,7 @@ export interface TaskBroker { unsubscribe: () => void; }; // (undocumented) - vacuumTasks(timeoutS: { timeoutS: number }): Promise; + vacuumTasks(options: { timeoutS: number }): Promise; } // @public diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts index 9df2b7146e..c03ba150c2 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts @@ -49,15 +49,32 @@ import { } from './github'; import { TemplateFilter } from '../../../lib'; import { TemplateAction } from '../types'; +import { getRootLogger } from '@backstage/backend-common'; -export const createBuiltinActions = (options: { +/** + * The options passed to {@link createBuiltinActions} + * @public + */ +export interface CreateBuiltInActionsOptions { reader: UrlReader; integrations: ScmIntegrations; catalogClient: CatalogApi; + /** @deprecated when the cookiecutter action is removed this won't be necessary */ containerRunner?: ContainerRunner; config: Config; additionalTemplateFilters?: Record; -}): TemplateAction[] => { +} + +/** + * A function to generate create a list of default actions that the scaffolder provides. + * Is called internally in the default setup, but can be used when adding your own actions or overriding the default ones + * + * @public + * @returns A list of actions that can be used in the scaffolder + */ +export const createBuiltinActions = ( + options: CreateBuiltInActionsOptions, +): TemplateAction[] => { const { reader, integrations, @@ -119,6 +136,11 @@ export const createBuiltinActions = (options: { ]; if (containerRunner) { + getRootLogger().warn( + `[DEPRECATED] The fetch:cookiecutter action will be removed part of the default scaffolder actions in later versions. +You can install the package seperately and remove the containerRunner from the createBuiltInActions to remove this warning, +or you can migrate to using fetch:template https://backstage.io/docs/features/software-templates/builtin-actions#migrating-from-fetchcookiecutter-to-fetchtemplate`, + ); actions.push( createFetchCookiecutterAction({ reader, diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.test.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.test.ts index a738afbe3f..d274ad3ba8 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.test.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.test.ts @@ -50,15 +50,6 @@ describe('fetchContent helper', () => { outputPath: os.tmpdir(), }; - it('should reject non string fetchUrls', async () => { - await expect( - fetchContents({ - ...options, - fetchUrl: false, - }), - ).rejects.toThrow('Invalid url parameter, expected string, got boolean'); - }); - it('should reject absolute file locations', async () => { await expect( fetchContents({ diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.ts index b56bab0d53..a01fcee6f7 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.ts @@ -15,12 +15,17 @@ */ import { resolveSafeChildPath, UrlReader } from '@backstage/backend-common'; -import { JsonValue } from '@backstage/types'; import { InputError } from '@backstage/errors'; import { ScmIntegrations } from '@backstage/integration'; import fs from 'fs-extra'; import path from 'path'; +/** + * A helper function that reads the contents of a directory from the given URL. + * Can be used in your own actions, and also used behind fetch:template and fetch:plain + * + * @public + */ export async function fetchContents({ reader, integrations, @@ -31,15 +36,9 @@ export async function fetchContents({ reader: UrlReader; integrations: ScmIntegrations; baseUrl?: string; - fetchUrl?: JsonValue; + fetchUrl?: string; outputPath: string; }) { - if (typeof fetchUrl !== 'string') { - throw new InputError( - `Invalid url parameter, expected string, got ${typeof fetchUrl}`, - ); - } - let fetchUrlIsAbsolute = false; try { // eslint-disable-next-line no-new diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/index.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/index.ts index 2265f9b4f7..5f4c04cc7d 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/index.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/index.ts @@ -15,12 +15,14 @@ */ export * from './catalog'; -export { createBuiltinActions } from './createBuiltinActions'; +export * from './createBuiltinActions'; export * from './debug'; export * from './fetch'; export * from './filesystem'; export * from './publish'; export * from './github'; +/** @deprecated please add this package to your own installation manually */ export { createFetchCookiecutterAction } from '@backstage/plugin-scaffolder-backend-module-cookiecutter'; + export { runCommand } from './helpers'; diff --git a/plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts b/plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts index 49c1056727..e7fd76ea9a 100644 --- a/plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts +++ b/plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts @@ -207,8 +207,8 @@ export class StorageTaskBroker implements TaskBroker { return { unsubscribe }; } - async vacuumTasks(timeoutS: { timeoutS: number }): Promise { - const { tasks } = await this.storage.listStaleTasks(timeoutS); + async vacuumTasks(options: { timeoutS: number }): Promise { + const { tasks } = await this.storage.listStaleTasks(options); await Promise.all( tasks.map(async task => { try { diff --git a/plugins/scaffolder-backend/src/scaffolder/tasks/types.ts b/plugins/scaffolder-backend/src/scaffolder/tasks/types.ts index c75b85f7b5..6cc3eabdc7 100644 --- a/plugins/scaffolder-backend/src/scaffolder/tasks/types.ts +++ b/plugins/scaffolder-backend/src/scaffolder/tasks/types.ts @@ -161,7 +161,7 @@ export interface TaskBroker { dispatch( options: TaskBrokerDispatchOptions, ): Promise; - vacuumTasks(timeoutS: { timeoutS: number }): Promise; + vacuumTasks(options: { timeoutS: number }): Promise; observe( options: { taskId: string;