Version update to v1.0.4, revision 48c788f

qawolf · Jan 3, 2025 · 8c38c54 · 8c38c54
1 parent 27ac3c0
commit 8c38c54
Show file tree

Hide file tree

Showing 11 changed files with 32,873 additions and 32,525 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## v1.0.4
+
+- Extract information from Github Event and send it to `attemptNotifyDeploy`
+
 ## v1.0.3
 
 - Add `qawolf-base-url` optional input

diff --git a/README.md b/README.md
@@ -2,8 +2,7 @@
 
 ## Introduction
 
-This action notifies QA Wolf that a deployment has been made, and initiate a run
-if a matching trigger was found. Under the hood, this action uses [the `@qawolf/ci-sdk`
+This action notifies QA Wolf that a deployment, including preview deployments, has been made. For standard deployments, it initiates a run if a matching trigger is found. For preview deployments, if there is a matching pull request testing button trigger, a comment is added to the pull request, allowing the developer to manually initiate a run when ready. Under the hood, this action uses [the `@qawolf/ci-sdk`
 package](https://www.npmjs.com/package/@qawolf/ci-sdk).
 
 ## Inputs
@@ -14,14 +13,6 @@ Refer to the [official documentation](https://qawolf.notion.site/Deploy-Success-
 
 **Required**. The QA Wolf API key, which you can find on the application's team settings page.
 
-### `sha`
-
-The SHA of the git commit to be tested. Depending on your setup, this might be necessary.
-
-### `branch`
-
-The git branch to be tested. This might also be required depending on your configuration.
-
 ### `deployment-type`
 
 The trigger deployment type.
@@ -34,111 +25,153 @@ The URL of the deployment to be tested.
 
 An advanced feature that allows you to control run superseding.
 
+### `variables`
+
+JSON-formatted environment variables for the deployment to be tested.
+
+## Auto-Extracted Inputs (Optional)
+
+The following inputs are automatically extracted from the GitHub event context. They only need to be specified if you want to override the default values.
+
+### `sha`
+
+The SHA of the git commit to be tested.
+
+### `branch`
+
+The git branch to be tested.
+
 ### `commit-url`
 
 If the GitHub application is not installed, you can pass the commit URL, and it will be displayed in the UI.
 
-### `variables`
+### `pull-request-number`
 
-JSON-formatted environment variables for the deployment to be tested.
+A pull request number associated with the deployment, if applicable.
 
 ## Outputs
 
 ### `run-id`
 
-The ID of the newly created run. This can be used with the `ci-greenlight` integration.
+The ID of the newly created run. Notice that for preview deployments, no run is automatically initiated and therefore no `run-id` will be available.
 
 ## Usage
 
 > ⚠️ The following parameters given in the `with` clause may vary depending on your setup.
 > Please contact a QA Wolf representative for more information.
 > See also [this documentation page](https://qawolf.notion.site/Choosing-Fields-Based-on-Your-Setup-dd72e46ceb7f451dae4e9ef06f64a2cc?pvs=24#e2578484633a41b89447423d7d960f2b).
 
-### Trigger action on `pull_request` events
+### Trigger action on `push` events
 
-[GitHub Docs: `pull_request` events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request)
+This action can also be triggered on `push` events to notify QA Wolf of a deployment to a main branch or other branches. A run is automatically initiated if a matching trigger is found.
+
+[GitHub Docs: `push` events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push)
 
 ```yml
 name: Deploy and Notify QA Wolf
-on: pull_request
+on:
+  push:
+    branches:
+      - main
 jobs:
   # The deployment URL should be captured in this step, unless the
   # URL is statically defined for the target environment.
-  deploy-preview-environmnent:
-    name: Your custom job to deploy a preview environment
+  deploy-environment:
+    name: Your custom job to deploy
     uses: ./your-custom-action
+  # !!IMPORTANT!!: If you don't wait for the deployment to be ready,
+  # we might test an outdated version of your app.
   wait-for-deployment:
     name: Your custom job to wait for the deployed environment to be ready
     uses: ./your-custom-action
   notify:
-    needs: deploy-preview-environmnent
+    needs: wait-for-deployment
     name: Trigger QA Wolf PR testing
     runs-on: ubuntu-latest
     steps:
+      # It is assumed that there is a deployment step before this one.
+      # The deployment URL should be captured in that step, unless the
+      # URL is statically defined for the target environment.
       - name: Notify QA Wolf of deployment
         uses: qawolf/notify-qawolf-on-deploy-action@v1
         env:
           GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
         with:
           qawolf-api-key: "${{ secrets.QAWOLF_API_KEY }}"
-          # THIS IS JUST AN EXAMPLE.
-          # The below parameters given in the `with` clause may vary depending on your setup.
-          sha: "${{ github.event.pull_request.head.sha }}"
-          branch: "${{ github.event.pull_request.head.ref }}"
-          # If not static, this URL should be captured in the deployment step, and passed
-          # down over here.
-          deployment-url: ${{ needs.deploy-preview-environmnent.outputs.deployment-url || "https://example.com" }}
+          # This URL should be captured in the deployment step.
+          deployment-url: ${{ needs.deploy-environment.outputs.deployment-url || "https://static-url.com" }}
 ```
 
-### Trigger action on `push` events
+### Trigger action on `pull_request` events
 
-[GitHub Docs: `push` events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push)
+Preview deployments are commonly used on pull requests to test changes before they are merged. This action can be triggered on `pull_request` events to notify QA Wolf of a preview deployment. Instead of automatically initiating a run, a comment is added to the pull request, allowing the developer to initiate a run when they are ready.
+
+[GitHub Docs: `pull_request` events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request)
 
 ```yml
 name: Deploy and Notify QA Wolf
-on:
-  push:
-    branches:
-      - main
+on: pull_request
 jobs:
-  # The deployment URL should be captured in this step, unless the
-  # URL is statically defined for the target environment.
+  # The preview deployment URL should be captured in this step
   deploy-preview-environmnent:
     name: Your custom job to deploy a preview environment
     uses: ./your-custom-action
+  # !!IMPORTANT!!: If you don't wait for the deployment to be ready,
+  # we might test an outdated version of your app.
   wait-for-deployment:
     name: Your custom job to wait for the deployed environment to be ready
     uses: ./your-custom-action
   notify:
-    needs: deploy-preview-environmnent
+    needs: wait-for-deployment
     name: Trigger QA Wolf PR testing
     runs-on: ubuntu-latest
     steps:
-      # It is assumed that there is a deployment step before this one.
-      # The deployment URL should be captured in that step, unless the
-      # URL is statically defined for the target environment.
-      - name: Notify QA Wolf of deployment
+      - name: Notify QA Wolf of preview deployment
         uses: qawolf/notify-qawolf-on-deploy-action@v1
         env:
           GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
         with:
           qawolf-api-key: "${{ secrets.QAWOLF_API_KEY }}"
-          # THIS IS JUST AN EXAMPLE.
-          # The below parameters given in the `with` clause may vary depending on your setup.
-          sha: "${{ github.sha }}"
-          branch: "${{ github.ref }}"
-          # If not static, this URL should be captured in the deployment step, and passed
-          # down over here.
-          deployment-url: ${{ needs.deploy-preview-environmnent.outputs.deployment-url || "https://example.com" }}
+          deployment-url: ${{ needs.deploy-preview-environment.outputs.deployment-url }}
+```
+
+### Trigger action on `deployment_status` events
+
+This workflow is ideal for setups using third-party deployment services (like Vercel, Netlify, or Heroku) that automatically create GitHub deployment statuses. Unlike the `push` or `pull_request` triggers that require you to manage the deployment process (and wait for the deployment to complete), this trigger responds directly to deployment status updates from your hosting provider.
+
+[GitHub Docs: `deployment_status` events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#deployment_status)
+
+```yaml
+name: Notify QA Wolf of Deployment
+on: deployment_status
+jobs:
+  notify:
+    name: Notify QA Wolf of deployment
+    runs-on: ubuntu-latest
+    steps:
+      - name: Notify QA Wolf of deployment
+        # Only notify QA Wolf if the deployment was successful
+        if: ${{ github.event.deployment_status.state  == 'success' }}
+        uses: qawolf/notify-qawolf-on-deploy-action@v1
+        with:
+          qawolf-api-key: "${{ secrets.QAWOLF_API_KEY }}"
+          # Note that target_url is "The optional link added to the status.".
+          # If your vendor is not setting the target_url, this action will not work.
+          # You can either contact your vendor or try to compose the URL by following your vendor documentation.
+          deployment-url: ${{ github.event.deployment_status.target_url }}
+        secrets:
+          # Required if trigger action is `deployment_status`
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-### Reading the output from a subsequent job
+### Reading the output from a subsequent job (optional)
 
 > ⚠️ This is not required if you are using our GitHub application in PRs. See this
 > [documentation page](https://qawolf.notion.site/Install-GitHub-GitLab-App-47cc1ec73f564808b73333b36ef85a11).
 
-The `qawolf/notify-deploy-action` will output a `run-id` of the initiated run.
-If you want to setup a job to poll the status of the run with our SDK
+The `qawolf/notify-deploy-action` will output a `run-id` of the initiated run for standard deployments. Note that for preview deployments, no run is automatically initiated and therefore no `run-id` will be available.
+
+If you want to setup a job to poll the status of the run with our SDK for standard deployments
 (see [this documentation page](https://www.notion.so/qawolf/Inspect-Run-Results-Programmatically-650df2f9a92a4c949d0da230015ee4d1)), you need to capture the run ID from the output.
 
 ```yml