docs

Author: GrantBirki

README.md

@@ -646,6 +646,7 @@ This section will cover a few suggestions and best practices that will help you
     2. Add Required Status Checks - Enforce that certain CI checks must pass before a pull request can be merged
       ![use-status-checks](./docs/assets/required-ci-checks.png)
 3. If you don't need to deploy PR forks (perhaps your project is internal and not open source), you can set the `allow_forks` input to `"false"` to prevent deployments from running on forks.
+4. You should **always** (unless you have a certain restriction) use the `sha` output variable over the `ref` output variable when deploying. It is more reliable for deployments, and safer from a security perspective. More details about using commit SHAs for deployments can be found [here](./docs/deploying-commit-SHAs.md).
 
 ## Alternate Command Syntax
 

docs/deploying-commit-SHAs.md

@@ -32,6 +32,8 @@ Do this:
 
 This ensures you are deploying the __exact__ commit SHA that branch-deploy has determined is safe to deploy. This is a best practice for security, reliability, and safety during deployments.
 
+Don't worry, this is still a _branch deployment_, you are just telling your deployment process to use the __exact commit SHA__ that the branch points to rather than the branch name itself which is mutable.
+
 ## Introduction
 
 Deploying commit SHAs (Secure Hash Algorithms) is a best practice in software development and deployment processes. This document explains the importance of deploying commit SHAs, focusing on aspects of security, reliability, and safety. It also provides an overview of how commit SHAs work under the hood in Git and how this contributes to the overall safety of the deployment process.