From ff1bb4c39ecf55d801b0c33244e292b6f0949ea7 Mon Sep 17 00:00:00 2001
From: bnechyporenko <bnechyporenko@bol.com>
Date: Mon, 1 Jul 2024 22:17:07 +0200
Subject: [PATCH] Added a documentation how to use checkpoints + the fix when
 to clean the workspace

Signed-off-by: bnechyporenko <bnechyporenko@bol.com>
---
 .changeset/kind-dancers-boil.md               |  5 ++++
 .../writing-custom-actions.md                 | 26 ++++++++++++++++++-
 .../tasks/NunjucksWorkflowRunner.ts           | 13 ++++++----
 3 files changed, 38 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/kind-dancers-boil.md

diff --git a/.changeset/kind-dancers-boil.md b/.changeset/kind-dancers-boil.md
new file mode 100644
index 0000000000..8e69e830df
--- /dev/null
+++ b/.changeset/kind-dancers-boil.md
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+Added a documentation how to use checkpoints + the fix when to clean the workspace
diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md
index e8b354bd45..41bd7d2026 100644
--- a/docs/features/software-templates/writing-custom-actions.md
+++ b/docs/features/software-templates/writing-custom-actions.md
@@ -145,6 +145,8 @@ When the action `handler` is called, we provide you a `context` as the only
 argument. It looks like the following:
 
 - `ctx.baseUrl` - a string where the template is located
+- `ctx.checkpoint` - _Experimental_ allows to implement idempotency of the actions by not re-running the same function again if it was
+  executed successfully on the previous run.
 - `ctx.logger` - a Winston logger for additional logging inside your action
 - `ctx.logStream` - a stream version of the logger if needed
 - `ctx.workspacePath` - a string of the working directory of the template run
@@ -153,7 +155,7 @@ argument. It looks like the following:
 - `ctx.output` - a function which you can call to set outputs that match the
   JSON schema or `zod` in `schema.output` for ex. `ctx.output('downloadUrl', myDownloadUrl)`
 - `createTemporaryDirectory` a function to call to give you a temporary
-  directory somewhere on the runner so you can store some files there rather
+  directory somewhere on the runner, so you can store some files there rather
   than polluting the `workspacePath`
 - `ctx.metadata` - an object containing a `name` field, indicating the template
   name. More metadata fields may be added later.
@@ -217,6 +219,28 @@ import {
     })
 ```
 
+### Using Checkpoints in Custom Actions (Experimental)
+
+Idempotent action could be achieved via the usage of checkpoints.
+
+Example:
+
+```ts
+const res = await ctx.checkpoint?.('create.projects', async () => {
+  const projectStgId = createStagingProjectId();
+  const projectProId = createProductionProjectId();
+
+  return {
+    projectStgId,
+    projectProId,
+  };
+});
+```
+
+You have to define the unique key in scope of the scaffolder task for your checkpoint. During the execution task engine
+will check if the checkpoint with such key was already executed or not, if yes, and the run was successful, the callback
+will be skipped and instead the stored value will be returned.
+
 ### Register Custom Actions with the Legacy Backend System
 
 Once you have your Custom Action ready for usage with the scaffolder, you'll
diff --git a/plugins/scaffolder-backend/src/scaffolder/tasks/NunjucksWorkflowRunner.ts b/plugins/scaffolder-backend/src/scaffolder/tasks/NunjucksWorkflowRunner.ts
index 3b88fd0f10..69f17e9dce 100644
--- a/plugins/scaffolder-backend/src/scaffolder/tasks/NunjucksWorkflowRunner.ts
+++ b/plugins/scaffolder-backend/src/scaffolder/tasks/NunjucksWorkflowRunner.ts
@@ -508,11 +508,11 @@ export class NunjucksWorkflowRunner implements WorkflowRunner {
 
       const output = this.render(task.spec.output, context, renderTemplate);
       await taskTrack.markSuccessful();
+      await task.cleanWorkspace?.();
 
       return { output };
     } finally {
       if (workspacePath) {
-        await task.cleanWorkspace?.();
         await fs.remove(workspacePath);
       }
     }
@@ -554,10 +554,13 @@ function scaffoldingTracker() {
       step: TaskStep,
       action: TemplateAction<JsonObject>,
     ) {
-      task.emitLog(`Skipping because ${action.id} does not support dry-run`, {
-        stepId: step.id,
-        status: 'skipped',
-      });
+      await task.emitLog(
+        `Skipping because ${action.id} does not support dry-run`,
+        {
+          stepId: step.id,
+          status: 'skipped',
+        },
+      );
     }
 
     async function markSuccessful() {