CI: add comments to GH workflows

.github/workflows/branch-integration-tests.yaml

@@ -1,3 +1,5 @@
+# The idea with this workflow is to allow core reviewers to trigger the
+# integration tests by pushing a branch to the sceptre repository.
 name: branch-integration-tests
 
 on:

.github/workflows/check.yaml

@@ -1,3 +1,4 @@
+# Execute sanity checks
 name: check
 
 on:

.github/workflows/comment-integration-tests.yaml

@@ -1,3 +1,8 @@
+# The idea with this workflow is to allow users to trigger an integration test
+# run from a PR however it doesn't work because github action does not allow
+# access to the github token when triggered from a PR.  The workflow fails with..
+# "Credentials could not be loaded, please check your action inputs: Could not load credentials from any providers"
+
 name: comment-integration-tests
 
 on:

.github/workflows/gate.yaml

@@ -1,3 +1,5 @@
+# Run integration tests when a PR is merged to master and publish a
+# docker container (with an `edge` tag) with the latest code
 name: gate
 
 on:

.github/workflows/integration-tests.yaml

@@ -18,6 +18,12 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       id-token: write
+    # There is only one AWS account for running integration tests and the tests are not designed
+    # to run concurrently in one account which is why we are disabling concurrency.
+    # The intention is to have all triggered integration tests execute serially in one queue,
+    # all triggered integration tests should wait in the queue however github is canceling
+    # waiting jobs in the queue. Github currently does not support the desired use case,
+    # more info at https://github.com/orgs/community/discussions/41518
     concurrency:
       group: integration-tests
       cancel-in-progress: false