feat: add when parameter to all commands (#56)

* feat: add 'when' parameter to all commands

In order to use the common `when` command parameter in an orb command, the orb command needs to have its own `when` parameter.

Here I'm adding `when` to each command so that `on_success`, `on_fail` or `always` can be plumbed through.

This is useful in circumstances where you may need to, say, install the Github CLI as part of the steps taken after a CI failure.

Example circleci.yml:
```yaml
commands:
    build-failure-pr-comment:
        steps:
            - gh/setup:
                when: on_fail
            - run: gh pr comment ...
                when: on_fail
```

* fix: update deployment test by fixing macos tests and adding more recent uubuntu images

---------

Co-authored-by: Jason Young <[email protected]>

Author: david-montano-circleci

.circleci/test-deploy.yml

@@ -54,7 +54,7 @@ workflows:
           filters: *filters
           matrix:
             parameters:
-              executor: ["docker-x86-debian", "linuxvm-x86-debian", "macos-x86", "apple-silicon", "arm"]
+              executor: ["docker-x86-debian", "apple-silicon-14", "apple-silicon-15", "linuxvm-arm-ubuntu-2004", "linuxvm-x86-ubuntu-2004", "linuxvm-arm-ubuntu-2204", "linuxvm-x86-ubuntu-2204", "linuxvm-arm-ubuntu-2404", "linuxvm-x86-ubuntu-2404"]
               version: [2.27.0, 2.40.0] # 2.27.0 is the last version that uses ".tar.gz" instead of ".zip" for macOS
       - orb-tools/pack:
           filters: *release-filters
@@ -72,18 +72,32 @@ executors:
   docker-x86-debian:
     docker:
       - image: cimg/base:current
-  macos-x86:
+  apple-silicon-14:
     macos:
-      xcode: 14.0.0
-    resource_class: macos.x86.medium.gen2
-  apple-silicon:
+      xcode: 14.3.1
+    resource_class: macos.m1.medium.gen1
+  apple-silicon-15:
     macos:
-      xcode: 15.0.0
+      xcode: 15.4.0
     resource_class: macos.m1.medium.gen1
-  arm:
+  linuxvm-arm-ubuntu-2004:
+    machine:
+      image: ubuntu-2004:2024.05.1
+    resource_class: arm.medium
+  linuxvm-x86-ubuntu-2004:
+    machine:
+      image: ubuntu-2004:2024.05.1
+  linuxvm-arm-ubuntu-2204:
+    machine:
+      image: ubuntu-2204:2024.05.1
+    resource_class: arm.medium
+  linuxvm-x86-ubuntu-2204:
+    machine:
+      image: ubuntu-2204:2024.05.1
+  linuxvm-arm-ubuntu-2404:
     machine:
-      image: ubuntu-2004:202101-01
+      image: ubuntu-2404:2024.05.1
     resource_class: arm.medium
-  linuxvm-x86-debian:
+  linuxvm-x86-ubuntu-2404:
     machine:
-      image: ubuntu-2004:202101-01
+      image: ubuntu-2404:2024.05.1

src/commands/clone.yml

@@ -15,6 +15,10 @@ parameters:
     type: string
     default: "."
     description: Select the path to clone into. By default the current path will be selected, which is dictated by the job's "working_directory".
+  when:
+    type: string
+    default: "on_success"
+    description: Specify when to run this command. Options are "on_success", "always" or "on_fail".
 steps:
   - run:
       name: Cloning repository
@@ -23,3 +27,4 @@ steps:
         PARAM_GH_DIR: <<parameters.dir>>
         PARAM_GH_HOSTNAME: <<parameters.hostname>>
       command: <<include(scripts/clone.sh)>>
+      when: <<parameters.when>>

src/commands/install.yml

@@ -4,9 +4,14 @@ parameters:
     type: string
     default: "2.40.1"
     description: Specify the full semver versioned tag to use.
+  when:
+    type: string
+    default: "on_success"
+    description: Specify when to run this command. Options are "on_success", "always" or "on_fail".
 steps:
   - run:
       environment:
         PARAM_GH_CLI_VERSION: <<parameters.version>>
       name: Install GH CLI v<<parameters.version>>
       command: <<include(scripts/install.sh)>>
+      when: <<parameters.when>>

src/commands/setup.yml

@@ -14,12 +14,18 @@ parameters:
     description: |
       Enter the name of the environment variable containing the GitHub Personal Access token to be used for authentication.
       It is recommended for CI processes that you create a "machine" user on GitHub.com with the needed permissions, rather than using your own.
+  when:
+    type: string
+    default: "on_success"
+    description: Specify when to run this command. Options are "on_success", "always" or "on_fail".
 steps:
   - install:
       version: <<parameters.version>>
+      when: <<parameters.when>>
   - run:
       environment:
         PARAM_GH_TOKEN: <<parameters.token>>
         PARAM_GH_HOSTNAME: <<parameters.hostname>>
       name: Configure GH CLI v<<parameters.version>>
       command: <<include(scripts/configure.sh)>>
+      when: <<parameters.when>>