feat: add fallback to GITHUB_SHA + more info in README

README.md

@@ -1,6 +1,6 @@
 # About
 
-GitHub Action to post deployment and deployment status to Echoes.
+GitHub Action to post [deployment](https://docs.echoeshq.com/deployments) and [deployment status](https://docs.echoeshq.com/change-failure-rate) to Echoes.
 
 ---
 
@@ -23,15 +23,22 @@ It requires to set the `ECHOES_API_KEY` environment variable with an [API key](h
 > The post of a deployment is idempotent.
 > Retrying a deployment with the **same payload** and **API key** will result in a single deployment in Echoes.
 
+In default mode, the action expects to work on [tags](https://docs.github.com/en/rest/git/tags?apiVersion=2022-11-28) in order to access a commits list.
+If no tags are found, it will fallback to the current commit sha `$GITHUB_SHA` that triggered the workflow. For more information, see [Events that trigger workflows](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows).
+
+> [!Important]
+> By default `EchoesHQ/deployments-action` do not require to be used in conjonction with the [`actions/checkout` Action](https://github.com/actions/checkout) because it can fallback to `$GITHUB_SHA`.
+> However if you are planning to work with [tags](https://docs.github.com/en/rest/git/tags?apiVersion=2022-11-28) make sure to set the appropriate `actions/checkout` options such as `fetch-depth` and `fetch-tags` to fine tuning to your need.
+
+> [!Warning]
+> Not any commits would be of interest. Indeed `Deployments` are used by Echoes to extract some critical information such as Teams and Echoes Labels. Could it be a list of commits extracted from tags or extracted from the `$GITHUB_SHA`, those have value for Echoes only if they are attached to a PR that was labeled with [Echoes labels](https://docs.echoeshq.com/categorizing-work). The commits would therefore be properly associated to the work they hold for the team they represent.
+
 ```yaml
 steps:
     - name: Checkout
-    uses: actions/checkout@v3
-    # In default mode, the action expects to work on tags in order to
-    # access a commits list. See Examples below for more details.
-    with:
-        fetch-depth: 100
-        fetch-tags: true
+      uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
 
     - name: Post deploy
         uses: EchoesHQ/deployments-action@v1
@@ -40,6 +47,8 @@ steps:
             ECHOES_API_KEY: ${{ secrets.ECHOESHQ_API_KEY }}
 ```
 
+See [Examples](#examples) below for more details.
+
 ### Post a deployment status to Echoes:
 
 ```yaml
@@ -61,12 +70,12 @@ steps:
   with:
     # Optional. Can either be `post-deploy` or `post-status`. Defaults to `post-deploy`.
     action-type: string
-    # Optional. Version being deployed. Defaults to tag.
-    version: string
-    # Optional. Newline-separated list of deliverables the deployment contains (e.g., microservice name, application name). Defaults to repository name.
+    # Required. Newline-separated list of deliverables the deployment contains (e.g., microservice name, application name). Defaults to repository name.
     deliverables: string
-    # Optional. Newline-separated list of commits SHA shipped as part of the deployment. Defaults to listing commits between the last 2 tags.
+    # Required. Newline-separated list of commits SHA shipped as part of the deployment. Defaults to listing commits between the last 2 tags or as a last fallback $GITHUB_SHA.
     commits: string
+    # Optional. Version being deployed.
+    version: string
     # Optional. URL related to the deployment: URL to a tag, to an artefact etc. Defaults to ${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/releases/tag/${tag}
     url: string
 ```

action.yml

@@ -3,14 +3,14 @@ name: "EchoesHQ Deployments Action"
 author: "EchoesHQ"
 description: "Declare deployments and notify their status to Echoes."
 inputs:
-  version:
-    description: "Version being deployed. Defaults to tag."
-    required: false
   deliverables:
     description: "Newline-separated list of deliverables the deployment contains (e.g., microservice name, application name)..."
     required: false
   commits:
-    description: "Newline-separated list of commits SHA shipped as part of the deployment. Defaults to listing commits between the last 2 tags."
+    description: "Newline-separated list of commits SHA shipped as part of the deployment. Defaults to listing commits between the last 2 tags or as a last fallback $GITHUB_SHA."
+    required: false
+  version:
+    description: "Version being deployed."
     required: false
   url:
     description: "URL related to the deployment: URL to a tag, to an artefact..."
@@ -39,7 +39,6 @@ runs:
     # to avoid having invalid arguments in getopts we artificially introduce a space (trimmed later on)
     - -t ${{ inputs.action-type }}
     - -v ${{ inputs.version }}
-    - -n ${{ inputs.name }}
     - -d ${{ inputs.deliverables }}
     - -c ${{ inputs.commits }}
     - -u ${{ inputs.url }}

entrypoint.sh

@@ -7,14 +7,12 @@ git config --global --add safe.directory "${GITHUB_WORKSPACE}"
 
 ECHOES_API_ENDPOINT="https://api.echoeshq.com/v1/signals/deployments"
 
-while getopts ":t:v:n:d:c:u:s:i:" opt; do
+while getopts ":t:v:d:c:u:s:i:" opt; do
     case $opt in
         t) action_type=$(trim "${OPTARG}")
         ;;
         v) version=$(trim "${OPTARG}")
         ;;
-        n) name=$(trim "${OPTARG}")
-        ;;
         d)
         mapfile -t deliverables < <(trim "${OPTARG}")
         ;;
@@ -39,13 +37,13 @@ while getopts ":t:v:n:d:c:u:s:i:" opt; do
     esac
 done
 
+# Makes sure the API KEY is provided
 if [ -z "${ECHOES_API_KEY}" ]
 then
     echo "No ECHOES_API_KEY provided! Please visit: https://docs.echoeshq.com/api-authentication#ZB9nc"
     exit 1
 fi
 
-
 # Is the action used to post a deployment status?
 if [ "${action_type}" == "post-status" ]
 then
@@ -74,48 +72,42 @@ then
     exit 0
 fi
 
-
+# If no deliverables provided look up for the GITHUB_REPOSITORY.
+# If the value could be empty.
 if [ -z "${deliverables[0]}" ] || [ "$(arraylength "${deliverables[@]}")" -eq 0 ]
 then
     echo "No deliverables list provided, defaults to \$GITHUB_REPOSITORY."
-    # Keep the repository name only as deliverable value
-    deliverables=( "${GITHUB_REPOSITORY//${GITHUB_REPOSITORY_OWNER}\//}" )
-fi
 
-if [ -z "${version}" ]
-then
-    latestTag=$(git for-each-ref refs/tags --sort=-authordate --format='%(refname:short)' --count=1 --merged)
-    if [ -z "${latestTag}" ]
+    if [ -z "${GITHUB_REPOSITORY}" ]
     then
-        echo "No version provided."
+        echo "\$GITHUB_REPOSITORY is missing. Please make sure to have used the actions/checkout or provide a deliverables list."
         exit 1
     fi
-    version="${latestTag}"
-
-    if [ -z "${name}" ]
-    then
-        name=${version}
-    fi
-fi
 
-if [ -z "${name}" ] && [ -n "${version}" ]
-then
-    name=${version}
+    # Keep the repository name only as deliverable value
+    deliverables=( "${GITHUB_REPOSITORY//${GITHUB_REPOSITORY_OWNER}\//}" )
 fi
 
+# If no commits provided look up for tags.
+# If no tags are found, look up for the commit SHA triggering the workflow (GITHUB_SHA).
 if [ -z "${commits[0]}" ] || [ "$(arraylength "${commits[@]}")" -eq 0 ]
 then
     # No commits list provided therefore look for tags
     echo "Looking for commits via tags..."
 
     latestTags=$(git for-each-ref refs/tags --sort=-authordate --format='%(refname:short)' --count=2 --merged)
 
-    echo "Last tags found for the current branch: ${latestTags}"
-
     if [ -z "${latestTags}" ]
     then
-        echo "No tags found, therefore no deployment can be submitted. -> link to the doc here"
-        exit 0
+        echo "No tags were found, therefore looking for \$GITHUB_SHA"
+        if [ -z "${GITHUB_SHA}" ]
+        then
+            echo "No tags were found, nor \$GITHUB_SHA therefore no deployment can be submitted."
+            echo "Please provide a commits list or make sure to have used the actions/checkout beforehand."
+            exit 1
+        else
+            commits=("${GITHUB_SHA}")
+        fi
     else
         mapfile -t tags <<< "$latestTags"
         numberOfTags=$(arraylength "${tags[@]}")
@@ -155,7 +147,6 @@ response=$(curl --silent --show-error --fail-with-body --location "${ECHOES_API_
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer '"${ECHOES_API_KEY}"'' \
 --data-raw '{
-    "name": "'"${name}"'",
     "version": "'"${version}"'",
     "commits": '"${commitsJSON}"',
     "deliverables": '"${deliverablesJSON}"',