add test and documentation

Author: Brend-Smits

docs/additional_notes.md

@@ -32,3 +32,31 @@ If default labels are removed:
 | 'custom5' | Linux | no match |
 | 'custom5' | [ self-hosted, Linux ] | no match |
 | 'custom5' | [ custom5, self-hosted, Linux ] | no match |
+
+# Preventing Runner Scale-Down for Debugging
+
+The module supports a bypass mechanism that allows you to prevent specific runners from being scaled down during debugging or investigation. This is useful when you need to access a runner instance directly to troubleshoot issues.
+
+## Usage
+
+To prevent a runner from being terminated during scale-down operations, add the `ghr:bypass-removal` tag to the EC2 instance with a value of `true`:
+
+```bash
+aws ec2 create-tags --resources <instance-id> --tags Key=ghr:bypass-removal,Value=true
+```
+
+When this tag is set, the scale-down process will skip the runner and log a message indicating that the runner is protected:
+
+```
+Runner 'i-xxxxxxxxxxxx' has bypass-removal tag set, skipping removal. Remove the tag to allow scale-down.
+```
+
+## Removing the Protection
+
+Once you've finished debugging and want to allow the runner to be scaled down normally, remove the tag or set it to any other value:
+
+```bash
+aws ec2 delete-tags --resources <instance-id> --tags Key=ghr:bypass-removal
+```
+
+**Note:** The bypass-removal tag only prevents automatic scale-down. The runner will still continue to process job(s) as normal. Make sure to remove the tag after debugging to ensure proper resource management. It will also still terminate itself if the instance is empheral and the job is complete.

lambdas/functions/control-plane/src/scale-runners/scale-down.test.ts

@@ -286,6 +286,25 @@ describe('Scale down runners', () => {
         checkNonTerminated(runners);
       });
 
+      it(`Should not terminate runner with bypass-removal tag set.`, async () => {
+        // setup
+        const runners = [
+          createRunnerTestData('idle-with-bypass', type, MINIMUM_TIME_RUNNING_IN_MINUTES + 10, true, false, false),
+        ];
+        // Set bypass-removal tag
+        runners[0].bypassRemoval = true;
+
+        mockGitHubRunners(runners);
+        mockAwsRunners(runners);
+
+        // act
+        await scaleDown();
+
+        // assert
+        expect(terminateRunner).not.toHaveBeenCalled();
+        checkNonTerminated(runners);
+      });
+
       it(`Should not terminate a runner that became busy just before deregister runner.`, async () => {
         // setup
         const runners = [