Various Upgrades / Updates 4.x (#26)

* feat: walk back, and use executor instead

* feat: update tools

* feat: upgrade

Author: promiseofcake

.circleci/config.yml

@@ -1,8 +1,8 @@
 version: 2.1
 setup: true
 orbs:
-  orb-tools: circleci/orb-tools@11.6
-  shellcheck: circleci/shellcheck@3.1
+  orb-tools: circleci/orb-tools@12.3
+  shellcheck: circleci/shellcheck@3.4
 
 filters: &filters
   tags:
@@ -21,14 +21,15 @@ workflows:
       - shellcheck/check:
           filters: *filters
       - orb-tools/publish:
-          orb-name: promiseofcake/workflow-queue
-          vcs-type: << pipeline.project.type >>
+          orb_name: promiseofcake/workflow-queue
+          vcs_type: << pipeline.project.type >>
           requires:
             [orb-tools/lint, orb-tools/review, orb-tools/pack, shellcheck/check]
           context: orb-publishing
           filters: *filters
       - orb-tools/continue:
-          pipeline-number: << pipeline.number >>
-          vcs-type: << pipeline.project.type >>
+          orb_name: promiseofcake/workflow-queue
+          pipeline_number: << pipeline.number >>
+          vcs_type: << pipeline.project.type >>
           requires: [orb-tools/publish]
           filters: *filters

.circleci/test-deploy.yml

@@ -1,12 +1,10 @@
 version: 2.1
 orbs:
+  orb-tools: circleci/[email protected]
   workflow-queue: promiseofcake/workflow-queue@dev:<<pipeline.git.revision>>
-  orb-tools: circleci/[email protected]
-
 filters: &filters
   tags:
     only: /.*/
-
 jobs:
   sleep:
     docker:
@@ -16,11 +14,10 @@ jobs:
         type: integer
     steps:
       - run: echo "sleeping << parameters.time >>s" &&  sleep << parameters.time >>
-
 workflows:
   test-pipeline-a:
     jobs:
-      - workflow-queue/pipeline-queue:
+      - workflow-queue/pipeline_queue:
           context: orb-publishing
           debug: true
   test-pipeline-b:
@@ -31,13 +28,12 @@ workflows:
     jobs:
       - sleep:
           time: 20
-
-  test-global-queue:
+  test-global_queue:
     jobs:
-      - workflow-queue/global-queue:
+      - workflow-queue/global_queue:
           context: orb-publishing
           debug: true
-          ignored-workflows: "test-pipeline-a" # given we are in one pipeline, don't block on ourselves
+          ignored_workflows: "test-pipeline-a" # given we are in one pipeline, don't block on ourselves
           filters:
             tags:
               ignore: /.*/
@@ -47,9 +43,9 @@ workflows:
           filters: *filters
       - orb-tools/publish:
           context: orb-publishing
-          orb-name: promiseofcake/workflow-queue
-          vcs-type: << pipeline.project.type >>
-          pub-type: production
+          orb_name: promiseofcake/workflow-queue
+          vcs_type: << pipeline.project.type >>
+          pub_type: production
           requires:
             - orb-tools/pack
           filters:

README.md

@@ -14,6 +14,31 @@ Additional use-cases are for queueing workflows within a given pipeline (a featu
 
 In order to use this orb you will need to export a `CIRCLECI_API_TOKEN` secret added to a context of your choosing. It will authentcation against the CircleCI API to check on workflow status. (see: <https://circleci.com/docs/api/v2/index.html#section/Authentication>)
 
+## Custom Executors
+
+Both `global-queue` and `pipeline-queue` jobs now support custom executors. By default, they use a small Docker executor with `cimg/base:stable`, but you can provide your own executor for more control over the execution environment.
+
+### Example: Using a Custom Docker Executor
+
+```yaml
+version: 2.1
+orbs:
+  workflow-queue: promiseofcake/workflow-queue@3
+
+executors:
+  nodejs-executor:
+    docker:
+      - image: cimg/node:18.0
+    resource_class: medium
+
+workflows:
+  deploy:
+    jobs:
+      - workflow-queue/global-queue:
+          context: deployment-context
+          executor: nodejs-executor
+```
+
 ---
 
 ## Resources

src/commands/global_block.yml

@@ -10,11 +10,11 @@ parameters:
     type: string
     default: "10"
     description: "Number of minutes to wait for a lock before giving up."
-  dont-quit:
+  dont_quit:
     type: boolean
     default: false
     description: "If true, forces the job through once time expires instead of failing."
-  only-on-branch:
+  only_on_branch:
     type: string
     default: "*"
     description: "Only queue on specified branch"
@@ -25,11 +25,11 @@ parameters:
       Due to concurrency issues, the number of times should we requery the pipeline list to ensure previous jobs are "pending",
       but not yet active. This number indicates the threshold for API returning no previous pending pipelines.
       Default is `1` confirmation, increase if you see issues.
-  ignored-workflows:
+  ignored_workflows:
     type: string
     default: ""
     description: Comma separated list of workflow names to ignore as blocking workflows for the global queue.
-  include-on-hold:
+  include_on_hold:
     type: boolean
     default: false
     description: Consider `on-hold` workflows waiting for approval as running and include them in the queue.
@@ -40,9 +40,9 @@ steps:
       environment:
         CONFIG_DEBUG_ENABLED: "<< parameters.debug >>"
         CONFIG_TIME: "<< parameters.time >>"
-        CONFIG_DONT_QUIT: "<< parameters.dont-quit >>"
-        CONFIG_ONLY_ON_BRANCH: "<< parameters.only-on-branch >>"
+        CONFIG_DONT_QUIT: "<< parameters.dont_quit >>"
+        CONFIG_ONLY_ON_BRANCH: "<< parameters.only_on_branch >>"
         CONFIG_CONFIDENCE: "<< parameters.confidence >>"
-        CONFIG_IGNORED_WORKFLOWS: "<< parameters.ignored-workflows >>"
-        CONFIG_INCLUDE_ON_HOLD: "<< parameters.include-on-hold >>"
-      command: <<include(scripts/global-queue.sh)>>
+        CONFIG_IGNORED_WORKFLOWS: "<< parameters.ignored_workflows >>"
+        CONFIG_INCLUDE_ON_HOLD: "<< parameters.include_on_hold >>"
+      command: <<include(scripts/global_queue.sh)>>

src/commands/pipeline_block.yml

@@ -20,4 +20,4 @@ steps:
       environment:
         CONFIG_DEBUG_ENABLED: "<< parameters.debug >>"
         CONFIG_CONFIDENCE: "<< parameters.confidence >>"
-      command: <<include(scripts/pipeline-queue.sh)>>
+      command: <<include(scripts/pipeline_queue.sh)>>

src/examples/global-queue.yml

@@ -0,0 +1,36 @@
+description: >
+  Use when you want to block a workflow progression until there is only one running.
+usage:
+  # Simple example - uses default cimg/base:stable executor automatically
+  version: 2.1
+  orbs:
+    workflow-queue: promiseofcake/workflow-queue@3
+
+  workflows:
+    example:
+      jobs:
+        - workflow-queue/global_queue:
+            name: workflow-queue
+            context: <context-key>
+            only_on_branch: main
+            # No executor specified - automatically uses cimg/base:stable
+
+  # Advanced example - custom executors
+  # version: 2.1
+  # orbs:
+  #   workflow-queue: promiseofcake/workflow-queue@3
+
+  # executors:
+  #   my-custom-executor:
+  #     docker:
+  #       - image: cimg/node:18.0
+  #     resource_class: medium
+
+  # workflows:
+  #   example:
+  #     jobs:
+  #       - workflow-queue/global_queue:
+  #           name: workflow-queue
+  #           context: <context-key>
+  #           only_on_branch: main
+  #           executor: my-custom-executor  # Override default with custom executor

src/examples/global_queue.yml

@@ -0,0 +1,36 @@
+description: >
+  Use when you want a single workflow to be run at the end of a given pipeline (internal queueing).
+usage:
+  # Simple example - uses default cimg/base:stable executor automatically
+  version: 2.1
+  orbs:
+    workflow-queue: promiseofcake/workflow-queue@3
+
+  workflows:
+    example:
+      jobs:
+        - workflow-queue/pipeline_queue:
+            name: pipeline_queue
+            context: <context-key>
+            only_on_branch: main
+            # No executor specified - automatically uses cimg/base:stable
+
+  # # Advanced example - custom executor
+  # version: 2.1
+  # orbs:
+  #   workflow-queue: promiseofcake/workflow-queue@3
+
+  # executors:
+  #   my-custom-executor:
+  #     docker:
+  #       - image: cimg/python:3.11
+  #     resource_class: small
+
+  # workflows:
+  #   example:
+  #     jobs:
+  #       - workflow-queue/pipeline_queue:
+  #           name: pipeline_queue
+  #           context: <context-key>
+  #           only_on_branch: main
+  #           executor: my-custom-executor  # Override default with custom executor

src/examples/pipeline-queue.yml

@@ -0,0 +1,5 @@
+description: >
+  Default executor for workflow-queue jobs. Uses a small resource class with the CircleCI base image.
+docker:
+  - image: cimg/base:stable
+resource_class: small