refine the notation sign action doc

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>

sign-action.md

@@ -1,28 +1,29 @@
-# Sign an OCI artifact with Notation in GitHub Actions
+# Sign an image with Notation in GitHub Actions
 
-This document walks you through how to create a GitHub Actions workflow to achieve following goals:
+This document walks you through how to create a GitHub Actions workflow to achieve the following goals:
 
-1. Generate an OCI artifact and push it to Azure Container Registry
-2. Sign the OCI artifact with Notation and Notation AKV plugin. The generated signature is automatically pushed to Azure Container Registry
+1. Build an image and push it to Azure Container Registry (ACR)
+2. Sign the image with Notation and Notation AKV plugin with a signing key stored in Azure Key Vault (AKV). The generated signature is automatically pushed to ACR
 
 ## Prerequisites
 
-- You have created a Key Vault in Azure Key Vault and created a self-signed signing key and certificate. You can follow this [doc](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-sign-build-push#create-a-self-signed-certificate-azure-cli) to create self-signed key and certificate for testing purposes
+- You have created a Key Vault in AKV and created a self-signed signing key and certificate. You can follow this [doc](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-sign-build-push#create-a-self-signed-certificate-azure-cli) to create self-signed key and certificate for testing purposes. 
 - You have created a registry in Azure Container Registry
-- You have a GitHub repository to store the sample workflow and GitHub Secret
+- You have a GitHub repository to store the sample workflow file and GitHub Secrets
 
-## Create GitHub Secret to store Azure credentials
+## Create GitHub Secrets to store credentials
 
-Enter your GitHub repository, create two encrypted secret two GitHub Secret `ACR_PASSWORD` and `AZURE_CREDENTIALS` to store credentials for authenticating with ACR and AKV:
+Enter your GitHub repository, create two encrypted secrets `ACR_PASSWORD` and `AZURE_CREDENTIALS` for the repository to authenticate with ACR and AKV. See the [GitHub doc](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) for details.
 
-- `ACR_PASSWORD`: the password to log in to the ACR where your artifact will be released
-- `AZURE_CREDENTIALS`: the credential to AKV where your key pair is stored.
+### Create a GitHub Secret `ACR_PASSWORD`
 
-See [GitHub Docs](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) for details.
+Create the first GitHub Secret naming `ACR_PASSWORD`, enter the password of your ACR registry where your image will be stored in the GitHub Secret value.
 
-Follow the steps below to get the value of `AZURE_CREDENTIALS` that we need to fill out in the GitHub Secret.
+### Create a GitHub Secret `AZURE_CREDENTIALS`
 
-- Execute the following command to create the service principal on Azure and generate Azure credentials. 
+Follow the steps below to get the value of `AZURE_CREDENTIALS`. This is credential to access your AKV where your signing key pair is stored.
+
+- Execute the following commands to create a new service principal on Azure. 
 
 ```
 # login using your own account
@@ -34,26 +35,30 @@ az ad sp create-for-rbac -n $spn --sdk-auth
 ```
 
 > [!IMPORTANT]
-> 1. Add the JSON output from the `az ad sp` command execution result to [Github Secret](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure?tabs=azure-portal%2Cwindows#add-the-service-principal-as-a-github-secret) `AZURE_CREDENTIALS` that we created in the previous step.
+> 1. Copy the entire JSON output from the `az ad sp` command execution result into the value of GitHub Secret `AZURE_CREDENTIALS`. See [this doc](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure?tabs=azure-portal%2Cwindows#add-the-service-principal-as-a-github-secret) for reference.
 >
 > 2. Save the `clientId` from the JSON output into an environment variable (without double quotes) as it will be needed in the next step:
 >```
 >  clientId=<clientId_from_JSON_output_of_last_step>
 >```
 
-- Grant AKV access permissions to the service principal that we created in the previous step.
+- Grant the AKV access permissions to the service principal that we created in the previous step.
 
 ```
 # set policy for your AKV
 akv=<your_akv_name>
 az keyvault set-policy --name $akv --spn $clientId --certificate-permissions get --key-permissions sign --secret-permissions get
 ```
 
-See [az keyvault set-policy](https://learn.microsoft.com/en-us/cli/azure/keyvault?view=azure-cli-latest#az-keyvault-set-policy) for details.
+See [az keyvault set-policy](https://learn.microsoft.com/en-us/cli/azure/keyvault?view=azure-cli-latest#az-keyvault-set-policy) for reference.
+
+### Create the GitHub Actions workflow
+
+- Create a `.github/workflows` directory in your repository on GitHub if this directory does not already exist.
 
-### Edit the sample workflow
+- In the `.github/workflows directory`, create a file named `<your_workflow>.yml`. For more information, see [Creating new files](https://docs.github.com/en/repositories/working-with-files/managing-files/creating-new-files).
 
-- Create `<your_gitrepo>/.github/workflows/<your_workflow>.yml` to run and test the CI/CD pipeline. You can copy the [signing template workflow](https://github.com/notation-playground/notation-integration-with-ACR-and-AKV/blob/template/sign-template.yml) from the collapsed section below to your own `<your_workflow>.yml` file. 
+- You can copy the [signing template workflow](https://github.com/notation-playground/notation-integration-with-ACR-and-AKV/blob/template/sign-template.yml) from the collapsed section below into your own `<your_workflow>.yml` file.
 
 - Update the environmental variables based on your environment by following the comments in the template. Save it and commit it to the repository.
 
@@ -74,7 +79,7 @@ env:
   ACR_USERNAME: <user_name_of_your_ACR>                 # example: myRegistry
   AKV_NAME: <your_Azure_Key_Vault_Name>                 # example: myAzureKeyVault
   KEY_ID: <key_id_of_your_private_key_to_sign_in_AKV>   # example: https://mynotationakv.vault.azure.net/keys/notationLeafCert/c585b8ad8fc542b28e41e555d9b3a1fd
-  NOTATION_EXPERIMENTAL: 1                              # [Optional] when set, can use Referrers API in the workflow
+  NOTATION_EXPERIMENTAL: 1                              # [Optional] when set, use Referrers API in the workflow
 
 jobs:
   notation-sign:
@@ -87,18 +92,18 @@ jobs:
         uses: actions/checkout@v3
       - name: prepare
         id: prepare
-        # using `v1` as an example tag, user can pick their own
+        # Use `v1` as an example tag, user can pick their own
         run: |
           echo "target_artifact_reference=${{ env.ACR_REGISTRY_NAME }}/${{ env.ACR_REPO_NAME }}:v1" >> "$GITHUB_ENV"
-      # Log into your ACR
+      # Log in to your ACR
       - name: docker login
         uses: azure/docker-login@v1
         with:
           login-server: ${{ env.ACR_REGISTRY_NAME }}
           username: ${{ env.ACR_USERNAME }}
           password: ${{ secrets.ACR_PASSWORD }}
-      # Build and Push an OCI artifact to ACR
-      # Using `Dockerfile` as an example to build an OCI artifact
+      # Build and push an image to ACR
+      # Use `Dockerfile` as an example to build an image
       - name: Build and push
         id: push
         uses: docker/build-push-action@v4
@@ -109,14 +114,14 @@ jobs:
       - name: Retrieve digest
         run: |
           echo "target_artifact_reference=${{ env.ACR_REGISTRY_NAME }}/${{ env.ACR_REPO_NAME }}@${{ steps.push.outputs.digest }}" >> "$GITHUB_ENV"
-      # Log into Azure in order to access AKV
+      # Log in to Azure in order to access AKV
       - name: Azure login
         uses: Azure/login@v1
         with:
           creds: ${{ secrets.AZURE_CREDENTIALS }}
           allow-no-subscriptions: true
 
-      # Install Notation CLI, the default version is "1.0.0"
+      # Install Notation CLI with the default version "1.0.0"
       - name: setup notation
         uses: notaryproject/notation-action/setup@main
 
@@ -141,14 +146,14 @@ jobs:
 
 </details>
 
-## Trigger the workflow
+## Trigger the GitHub Actions workflow
 
-The workflow trigger logic has been set to `on: push` [event](https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#using-events-to-trigger-workflows) so the workflow will run when a commit push is made to any branch in the workflow's repository.
+The workflow trigger logic has been set to `on: push` [event](https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#using-events-to-trigger-workflows) in the sample workflow. Committing the workflow file to a branch in your repository triggers the push event and runs your workflow.
 
-When a new git commit is pushed to the registry, Notation workflow will build and sign every build and push the signed image with its associated signature to the registry. On success, you will be able to see the image pushed to your ACR with a COSE format signature attached.
+On success, you will be able to see the image is built and pushed to your ACR with a COSE format signature attached.
 
-Another use case is to trigger the workflow when a new tag is pushed to the Github repo. See [this doc](https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#example-excluding-branches-and-tags) for details. This use case is typical in the software release process.
+Another use case is to trigger the workflow when a new tag is pushed to the Github repository. See [this doc](https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#example-excluding-branches-and-tags) for details. It is typical to secure a software release process with the trigger event in the GitHub Actions.
 
-## Check the GitHub Actions workflow status
+## View your GitHub Actions workflow results
 
-See the workflow logs from the GitHub Actions in your own repository.
+Under your GitHub repository name, click **Actions** tab of your GitHub repository to see the workflow logs.