diff --git a/.changeset/lovely-ladybugs-taste.md b/.changeset/lovely-ladybugs-taste.md new file mode 100644 index 0000000000..24017e4dee --- /dev/null +++ b/.changeset/lovely-ladybugs-taste.md @@ -0,0 +1,10 @@ +--- +'@backstage/plugin-scaffolder-backend': patch +--- + +**Deprecations**: The following are deprecated and should instead be imported from the new package `@backstage/plugin-scaffolder-node`: + +- `ActionContext` +- `createTemplateAction` +- `TaskSecrets` +- `TemplateAction` diff --git a/docs/backend-system/building-backends/08-migrating.md b/docs/backend-system/building-backends/08-migrating.md index fcac599227..71e5b52c24 100644 --- a/docs/backend-system/building-backends/08-migrating.md +++ b/docs/backend-system/building-backends/08-migrating.md @@ -390,8 +390,7 @@ depends on the appropriate extension point and interacts with it. ```diff // packages/backend/src/index.ts - // TODO: This might be moved to @backstage/plugin-scaffolder-node -+import { scaffolderActionsExtensionPoint } from '@backstage/plugin-scaffolder-backend/alpha'; ++import { scaffolderActionsExtensionPoint } from '@backstage/plugin-scaffolder-node'; +import { createBackendModule } from '@backstage/backend-plugin-api'; +const scaffolderExtensionsModule = createBackendModule({ diff --git a/plugins/scaffolder-backend/api-report.md b/plugins/scaffolder-backend/api-report.md index 8fcc8be47e..22cc0cae20 100644 --- a/plugins/scaffolder-backend/api-report.md +++ b/plugins/scaffolder-backend/api-report.md @@ -5,6 +5,7 @@ ```ts /// +import { ActionContext as ActionContext_2 } from '@backstage/plugin-scaffolder-node'; import { BackendFeature } from '@backstage/backend-plugin-api'; import { CatalogApi } from '@backstage/catalog-client'; import { CatalogProcessor } from '@backstage/plugin-catalog-backend'; @@ -27,17 +28,20 @@ import { PluginTaskScheduler } from '@backstage/backend-tasks'; import { ScmIntegrationRegistry } from '@backstage/integration'; import { ScmIntegrations } from '@backstage/integration'; import { SpawnOptionsWithoutStdio } from 'child_process'; -import { TaskSecrets } from '@backstage/plugin-scaffolder-node'; +import { TaskSecrets as TaskSecrets_2 } from '@backstage/plugin-scaffolder-node'; import { TaskSpec } from '@backstage/plugin-scaffolder-common'; import { TaskSpecV1beta3 } from '@backstage/plugin-scaffolder-common'; -import { TemplateAction } from '@backstage/plugin-scaffolder-node'; +import { TemplateAction as TemplateAction_2 } from '@backstage/plugin-scaffolder-node'; import { UrlReader } from '@backstage/backend-common'; import { Writable } from 'stream'; +// @public @deprecated (undocumented) +export type ActionContext = ActionContext_2; + // @public export const createBuiltinActions: ( options: CreateBuiltInActionsOptions, -) => TemplateAction[]; +) => TemplateAction_2[]; // @public export interface CreateBuiltInActionsOptions { @@ -54,7 +58,7 @@ export interface CreateBuiltInActionsOptions { export function createCatalogRegisterAction(options: { catalogClient: CatalogApi; integrations: ScmIntegrations; -}): TemplateAction< +}): TemplateAction_2< | { catalogInfoUrl: string; optional?: boolean | undefined; @@ -67,13 +71,13 @@ export function createCatalogRegisterAction(options: { >; // @public -export function createCatalogWriteAction(): TemplateAction<{ +export function createCatalogWriteAction(): TemplateAction_2<{ filePath?: string | undefined; entity: Entity; }>; // @public -export function createDebugLogAction(): TemplateAction<{ +export function createDebugLogAction(): TemplateAction_2<{ message?: string | undefined; listWorkspace?: boolean | undefined; }>; @@ -81,7 +85,7 @@ export function createDebugLogAction(): TemplateAction<{ // @public export function createFetchCatalogEntityAction(options: { catalogClient: CatalogApi; -}): TemplateAction<{ +}): TemplateAction_2<{ entityRef: string; optional?: boolean | undefined; }>; @@ -90,7 +94,7 @@ export function createFetchCatalogEntityAction(options: { export function createFetchPlainAction(options: { reader: UrlReader; integrations: ScmIntegrations; -}): TemplateAction<{ +}): TemplateAction_2<{ url: string; targetPath?: string | undefined; }>; @@ -101,7 +105,7 @@ export function createFetchTemplateAction(options: { integrations: ScmIntegrations; additionalTemplateFilters?: Record; additionalTemplateGlobals?: Record; -}): TemplateAction<{ +}): TemplateAction_2<{ url: string; targetPath?: string | undefined; values: any; @@ -113,12 +117,12 @@ export function createFetchTemplateAction(options: { }>; // @public -export const createFilesystemDeleteAction: () => TemplateAction<{ +export const createFilesystemDeleteAction: () => TemplateAction_2<{ files: string[]; }>; // @public -export const createFilesystemRenameAction: () => TemplateAction<{ +export const createFilesystemRenameAction: () => TemplateAction_2<{ files: Array<{ from: string; to: string; @@ -130,7 +134,7 @@ export const createFilesystemRenameAction: () => TemplateAction<{ export function createGithubActionsDispatchAction(options: { integrations: ScmIntegrations; githubCredentialsProvider?: GithubCredentialsProvider; -}): TemplateAction<{ +}): TemplateAction_2<{ repoUrl: string; workflowId: string; branchOrTagName: string; @@ -146,7 +150,7 @@ export function createGithubActionsDispatchAction(options: { export function createGithubIssuesLabelAction(options: { integrations: ScmIntegrationRegistry; githubCredentialsProvider?: GithubCredentialsProvider; -}): TemplateAction<{ +}): TemplateAction_2<{ repoUrl: string; number: number; labels: string[]; @@ -176,7 +180,7 @@ export type CreateGithubPullRequestClientFactoryInput = { export function createGithubRepoCreateAction(options: { integrations: ScmIntegrationRegistry; githubCredentialsProvider?: GithubCredentialsProvider; -}): TemplateAction<{ +}): TemplateAction_2<{ repoUrl: string; description?: string | undefined; homepage?: string | undefined; @@ -243,7 +247,7 @@ export function createGithubRepoPushAction(options: { integrations: ScmIntegrationRegistry; config: Config; githubCredentialsProvider?: GithubCredentialsProvider; -}): TemplateAction<{ +}): TemplateAction_2<{ repoUrl: string; description?: string | undefined; defaultBranch?: string | undefined; @@ -282,7 +286,7 @@ export function createGithubWebhookAction(options: { integrations: ScmIntegrationRegistry; defaultWebhookSecret?: string; githubCredentialsProvider?: GithubCredentialsProvider; -}): TemplateAction<{ +}): TemplateAction_2<{ repoUrl: string; webhookUrl: string; webhookSecret?: string | undefined; @@ -297,7 +301,7 @@ export function createGithubWebhookAction(options: { export function createPublishAzureAction(options: { integrations: ScmIntegrationRegistry; config: Config; -}): TemplateAction<{ +}): TemplateAction_2<{ repoUrl: string; description?: string | undefined; defaultBranch?: string | undefined; @@ -312,7 +316,7 @@ export function createPublishAzureAction(options: { export function createPublishBitbucketAction(options: { integrations: ScmIntegrationRegistry; config: Config; -}): TemplateAction<{ +}): TemplateAction_2<{ repoUrl: string; description?: string | undefined; defaultBranch?: string | undefined; @@ -329,7 +333,7 @@ export function createPublishBitbucketAction(options: { export function createPublishBitbucketCloudAction(options: { integrations: ScmIntegrationRegistry; config: Config; -}): TemplateAction<{ +}): TemplateAction_2<{ repoUrl: string; description?: string | undefined; defaultBranch?: string | undefined; @@ -342,7 +346,7 @@ export function createPublishBitbucketCloudAction(options: { export function createPublishBitbucketServerAction(options: { integrations: ScmIntegrationRegistry; config: Config; -}): TemplateAction<{ +}): TemplateAction_2<{ repoUrl: string; description?: string | undefined; defaultBranch?: string | undefined; @@ -359,7 +363,7 @@ export function createPublishBitbucketServerAction(options: { export function createPublishGerritAction(options: { integrations: ScmIntegrationRegistry; config: Config; -}): TemplateAction<{ +}): TemplateAction_2<{ repoUrl: string; description: string; defaultBranch?: string | undefined; @@ -373,7 +377,7 @@ export function createPublishGerritAction(options: { export function createPublishGerritReviewAction(options: { integrations: ScmIntegrationRegistry; config: Config; -}): TemplateAction<{ +}): TemplateAction_2<{ repoUrl: string; branch?: string | undefined; sourcePath?: string | undefined; @@ -387,7 +391,7 @@ export function createPublishGithubAction(options: { integrations: ScmIntegrationRegistry; config: Config; githubCredentialsProvider?: GithubCredentialsProvider; -}): TemplateAction<{ +}): TemplateAction_2<{ repoUrl: string; description?: string | undefined; homepage?: string | undefined; @@ -460,7 +464,7 @@ export const createPublishGithubPullRequestAction: ({ integrations, githubCredentialsProvider, clientFactory, -}: CreateGithubPullRequestActionOptions) => TemplateAction<{ +}: CreateGithubPullRequestActionOptions) => TemplateAction_2<{ title: string; branchName: string; description: string; @@ -477,7 +481,7 @@ export const createPublishGithubPullRequestAction: ({ export function createPublishGitlabAction(options: { integrations: ScmIntegrationRegistry; config: Config; -}): TemplateAction<{ +}): TemplateAction_2<{ repoUrl: string; defaultBranch?: string | undefined; repoVisibility?: 'internal' | 'private' | 'public' | undefined; @@ -493,7 +497,7 @@ export function createPublishGitlabAction(options: { // @public export const createPublishGitlabMergeRequestAction: (options: { integrations: ScmIntegrationRegistry; -}) => TemplateAction<{ +}) => TemplateAction_2<{ repoUrl: string; title: string; description: string; @@ -510,6 +514,11 @@ export const createPublishGitlabMergeRequestAction: (options: { // @public export function createRouter(options: RouterOptions): Promise; +// @public @deprecated (undocumented) +export const createTemplateAction: ( + templateAction: TemplateAction_2, +) => TemplateAction_2; + // @public export type CreateWorkerOptions = { taskBroker: TaskBroker; @@ -525,7 +534,7 @@ export type CreateWorkerOptions = { // @public export interface CurrentClaimedTask { createdBy?: string; - secrets?: TaskSecrets; + secrets?: TaskSecrets_2; spec: TaskSpec; taskId: string; } @@ -606,7 +615,7 @@ export type OctokitWithPullRequestPluginClient = Octokit & { // @public export interface RouterOptions { // (undocumented) - actions?: TemplateAction[]; + actions?: TemplateAction_2[]; // (undocumented) additionalTemplateFilters?: Record; // (undocumented) @@ -664,7 +673,7 @@ export const scaffolderPlugin: ( // @alpha export type ScaffolderPluginOptions = { - actions?: TemplateAction[]; + actions?: TemplateAction_2[]; taskWorkers?: number; taskBroker?: TaskBroker; additionalTemplateFilters?: Record; @@ -679,7 +688,7 @@ export type SerializedTask = { createdAt: string; lastHeartbeatAt?: string; createdBy?: string; - secrets?: TaskSecrets; + secrets?: TaskSecrets_2; }; // @public @@ -716,7 +725,7 @@ export interface TaskBroker { // @public export type TaskBrokerDispatchOptions = { spec: TaskSpec; - secrets?: TaskSecrets; + secrets?: TaskSecrets_2; createdBy?: string; }; @@ -743,7 +752,7 @@ export interface TaskContext { // (undocumented) isDryRun?: boolean; // (undocumented) - secrets?: TaskSecrets; + secrets?: TaskSecrets_2; // (undocumented) spec: TaskSpec; } @@ -770,11 +779,14 @@ export class TaskManager implements TaskContext { // (undocumented) getWorkspaceName(): Promise; // (undocumented) - get secrets(): TaskSecrets | undefined; + get secrets(): TaskSecrets_2 | undefined; // (undocumented) get spec(): TaskSpecV1beta3; } +// @public @deprecated (undocumented) +export type TaskSecrets = TaskSecrets_2; + // @public export type TaskStatus = | 'open' @@ -825,7 +837,7 @@ export interface TaskStore { export type TaskStoreCreateTaskOptions = { spec: TaskSpec; createdBy?: string; - secrets?: TaskSecrets; + secrets?: TaskSecrets_2; }; // @public @@ -862,14 +874,18 @@ export class TaskWorker { start(): void; } +// @public @deprecated (undocumented) +export type TemplateAction = + TemplateAction_2; + // @public export class TemplateActionRegistry { // (undocumented) - get(actionId: string): TemplateAction; + get(actionId: string): TemplateAction_2; // (undocumented) - list(): TemplateAction[]; + list(): TemplateAction_2[]; // (undocumented) - register(action: TemplateAction): void; + register(action: TemplateAction_2): void; } // @public (undocumented) diff --git a/plugins/scaffolder-backend/src/deprecated.ts b/plugins/scaffolder-backend/src/deprecated.ts new file mode 100644 index 0000000000..363e72a867 --- /dev/null +++ b/plugins/scaffolder-backend/src/deprecated.ts @@ -0,0 +1,104 @@ +/* + * Copyright 2023 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { + ActionContext as ActionContextNode, + createTemplateAction as createTemplateActionNode, + TaskSecrets as TaskSecretsNode, + TemplateAction as TemplateActionNode, +} from '@backstage/plugin-scaffolder-node'; +import { JsonObject } from '@backstage/types'; + +/** + * @public + * @deprecated Use `ActionContext` from `@backstage/plugin-scaffolder-node` instead + */ +export type ActionContext = + ActionContextNode; + +/** + * @public + * @deprecated Use `createTemplateAction` from `@backstage/plugin-scaffolder-node` instead + */ +export const createTemplateAction = createTemplateActionNode; + +/** + * @public + * @deprecated Use `TaskSecrets` from `@backstage/plugin-scaffolder-node` instead + */ +export type TaskSecrets = TaskSecretsNode; + +/** + * @public + * @deprecated Use `TemplateAction` from `@backstage/plugin-scaffolder-node` instead + */ +export type TemplateAction = + TemplateActionNode; + +/* +// @public +export type ActionContext = { + logger: Logger; + logStream: Writable; + secrets?: TaskSecrets; + workspacePath: string; + input: Input; + output(name: string, value: JsonValue): void; + createTemporaryDirectory(): Promise; + templateInfo?: TemplateInfo; + isDryRun?: boolean; + user?: { + entity?: UserEntity; + ref?: string; + }; +}; + +// @public +export const createTemplateAction: ( + templateAction: TemplateAction, +) => TemplateAction; + +// @alpha +export interface ScaffolderActionsExtensionPoint { + // (undocumented) + addActions(...actions: TemplateAction[]): void; +} + +// @alpha +export const scaffolderActionsExtensionPoint: ExtensionPoint; + +// @public +export type TaskSecrets = Record & { + backstageToken?: string; +}; + +// @public (undocumented) +export type TemplateAction = { + id: string; + description?: string; + examples?: { + description: string; + example: string; + }[]; + supportsDryRun?: boolean; + schema?: { + input?: Schema; + output?: Schema; + }; + handler: (ctx: ActionContext) => Promise; +}; +``` +*/ diff --git a/plugins/scaffolder-backend/src/index.ts b/plugins/scaffolder-backend/src/index.ts index 985ada405e..eb7a831bd0 100644 --- a/plugins/scaffolder-backend/src/index.ts +++ b/plugins/scaffolder-backend/src/index.ts @@ -27,3 +27,5 @@ export * from './processor'; export * from './extension'; export { scaffolderPlugin } from './ScaffolderPlugin'; export type { ScaffolderPluginOptions } from './ScaffolderPlugin'; + +export * from './deprecated'; diff --git a/plugins/scaffolder-node/api-report.md b/plugins/scaffolder-node/api-report.md index 95a2c81381..506ea0517d 100644 --- a/plugins/scaffolder-node/api-report.md +++ b/plugins/scaffolder-node/api-report.md @@ -15,12 +15,12 @@ import { UserEntity } from '@backstage/catalog-model'; import { Writable } from 'stream'; // @public -export type ActionContext = { +export type ActionContext = { logger: Logger; logStream: Writable; secrets?: TaskSecrets; workspacePath: string; - input: Input; + input: TInput; output(name: string, value: JsonValue): void; createTemporaryDirectory(): Promise; templateInfo?: TemplateInfo; @@ -51,7 +51,7 @@ export type TaskSecrets = Record & { }; // @public (undocumented) -export type TemplateAction = { +export type TemplateAction = { id: string; description?: string; examples?: { @@ -63,6 +63,6 @@ export type TemplateAction = { input?: Schema; output?: Schema; }; - handler: (ctx: ActionContext) => Promise; + handler: (ctx: ActionContext) => Promise; }; ``` diff --git a/plugins/scaffolder-node/src/actions/types.ts b/plugins/scaffolder-node/src/actions/types.ts index 385096ef4d..5a4f5796a1 100644 --- a/plugins/scaffolder-node/src/actions/types.ts +++ b/plugins/scaffolder-node/src/actions/types.ts @@ -26,12 +26,12 @@ import { UserEntity } from '@backstage/catalog-model'; * ActionContext is passed into scaffolder actions. * @public */ -export type ActionContext = { +export type ActionContext = { logger: Logger; logStream: Writable; secrets?: TaskSecrets; workspacePath: string; - input: Input; + input: TInput; output(name: string, value: JsonValue): void; /** @@ -63,7 +63,7 @@ export type ActionContext = { }; /** @public */ -export type TemplateAction = { +export type TemplateAction = { id: string; description?: string; examples?: { description: string; example: string }[]; @@ -72,5 +72,5 @@ export type TemplateAction = { input?: Schema; output?: Schema; }; - handler: (ctx: ActionContext) => Promise; + handler: (ctx: ActionContext) => Promise; };