Cleanup README and add some more informative messaging (#149)

README.md

@@ -1,12 +1,13 @@
+
 # Manual Workflow Approval
 
 [![ci](https://github.com/trstringer/manual-approval/actions/workflows/ci.yaml/badge.svg)](https://github.com/trstringer/manual-approval/actions/workflows/ci.yaml)
 
 Pause a GitHub Actions workflow and require manual approval from one or more approvers before continuing.
 
-This is a very common feature for a deployment or release pipeline, and while [this functionality is available from GitHub](https://docs.github.com/en/actions/managing-workflow-runs/reviewing-deployments), it requires the use of environments and if you want to use this for private repositories then you need GitHub Enterprise. This action provides manual approval without the use of environments, and is freely available to use on private repositories.
+This is a very common feature for a deployment or release pipeline, and while [this functionality is available from GitHub](https://docs.github.com/en/actions/managing-workflow-runs/reviewing-deployments), it requires the use of environments and if you want to use this for private repositories, then you need GitHub Enterprise. This action provides manual approval without the use of environments, and is freely available to use on private repositories.
 
-*Note: This approval duration is subject to the broader 72 hours timeout for a workflow. So keep that in mind when figuring out how quickly an approver must respond.*
+*Note: This approval duration is subject to the broader 35 day timeout for a workflow, as well as usage costs. So keep that in mind when figuring out how quickly an approver must respond. See [limitations](#limitations) for more information.*
 
 The way this action works is the following:
 
@@ -34,17 +35,23 @@ steps:
       issue-title: "Deploying v1.3.5 to prod from staging"
       issue-body: "Please approve or deny the deployment of version v1.3.5."
       exclude-workflow-initiator-as-approver: false
+      fail-on-denial: true
       additional-approved-words: ''
       additional-denied-words: ''
 ```
 
-- `approvers` is a comma-delimited list of all required approvers. An approver can either be a user or an org team. (*Note: Required approvers must have the ability to be set as approvers in the repository. If you add an approver that doesn't have this permission then you would receive an HTTP/402 Validation Failed error when running this action*)
-- `minimum-approvals` is an integer that sets the minimum number of approvals required to progress the workflow. Defaults to ALL approvers.
-- `issue-title` is a string that will be appended to the title of the issue.
-- `issue-body` is a string that will be prepended to the body of the issue.
-- `exclude-workflow-initiator-as-approver` is a boolean that indicates if the workflow initiator (determined by the `GITHUB_ACTOR` environment variable) should be filtered from the final list of approvers. This is optional and defaults to `false`. Set this to `true` to prevent users in the `approvers` list from being able to self-approve workflows.
-- `additional-approved-words` is a comma separated list of strings to expand the dictionary of words that indicate approval. This is optional and defaults to an empty string.
-- `additional-denied-words` is a comma separated list of strings to expand the dictionary of words that indicate denial. This is optional and defaults to an empty string.
+* `approvers` is a comma-delimited list of all required approvers. An approver can either be a user or an org team. (*Note: Required approvers must have the ability to be set as approvers in the repository. If you add an approver that doesn't have this permission then you would receive an HTTP/402 Validation Failed error when running this action*)
+* `minimum-approvals` is an integer that sets the minimum number of approvals required to progress the workflow. Defaults to ALL approvers.
+* `issue-title` is a string that will be appended to the title of the issue.
+* `issue-body` is a string that will be prepended to the body of the issue.
+* `exclude-workflow-initiator-as-approver` is a boolean that indicates if the workflow initiator (determined by the `GITHUB_ACTOR` environment variable) should be filtered from the final list of approvers. This is optional and defaults to `false`. Set this to `true` to prevent users in the `approvers` list from being able to self-approve workflows.
+* `fail-on-denial` is a boolean that indicates if the workflow should fail if any approver denies the approval. This is optional and defaults to `true`. Set this to `false` to allow the workflow to continue if any approver denies the approval.
+* `additional-approved-words` is a comma separated list of strings to expand the dictionary of words that indicate approval. This is optional and defaults to an empty string.
+* `additional-denied-words` is a comma separated list of strings to expand the dictionary of words that indicate denial. This is optional and defaults to an empty string.
+
+### Outputs
+
+* `approval_status` is a string that indicates the final status of the approval. This will be either `approved` or `denied`.
 
 ### Creating Issues in a different repository
 
@@ -124,8 +131,10 @@ For more information on permissions, please look at the [GitHub documentation](h
 ## Limitations
 
 * While the workflow is paused, it will still continue to consume a concurrent job allocation out of the [max concurrent jobs](https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration#usage-limits).
-* A job (including a paused job) will be failed [after 6 hours](https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration#usage-limits).
 * A paused job is still running compute/instance/virtual machine and will continue to incur costs.
+* Expirations (also mentioned elsewhere in this document):
+  * A job (including a paused job) will be failed [after 6 hours, and a workflow will be failed after 35 days](https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration#usage-limits).
+  * GitHub App tokens expire after 1 hour which implies duration for the approval cannot exceed 60 minutes or the job will fail due to bad credentials. See [docs](https://docs.github.com/en/rest/apps/apps#create-an-installation-access-token-for-an-app)
 
 ## Development
 
@@ -139,16 +148,16 @@ To test out your code in an action, you need to build the image and push it to a
 
 Build the image:
 
-```
-$ VERSION=1.7.1-rc.1 make IMAGE_REPO=ghcr.io/trstringer/manual-approval-test build
+```shell
+VERSION=1.7.1-rc.1 make IMAGE_REPO=ghcr.io/trstringer/manual-approval-test build
 ```
 
 *Note: The image version can be whatever you want, as this image wouldn't be pushed to production. It is only for testing.*
 
 Push the image to your container registry:
 
-```
-$ VERSION=1.7.1-rc.1 make IMAGE_REPO=ghcr.io/trstringer/manual-approval-test push
+```shell
+VERSION=1.7.1-rc.1 make IMAGE_REPO=ghcr.io/trstringer/manual-approval-test push
 ```
 
 To test out the image you will need to modify `action.yaml` so that it points to your new image that you're testing:
@@ -174,10 +183,10 @@ For `uses`, this should point to your repo and dev branch.
 ### Create a release
 
 1. Build the new version's image: `$ VERSION=1.7.0 make build`
-1. Push the new image: `$ VERSION=1.7.0 make push`
-1. Create a release branch and modify `action.yaml` to point to the new image
-1. Open and merge a PR to add these changes to the default branch
-1. Make sure to fetch the new changes into your local repo: `$ git checkout main && git fetch origin && git merge origin main`
-1. Delete the `v1` tag locally and remotely: `$ git tag -d v1 && git push --delete origin v1`
-1. Create and push new tags: `$ git tag v1.7.0 && git tag v1 && git push origin --tags`
-1. Create the GitHub project release
+2. Push the new image: `$ VERSION=1.7.0 make push`
+3. Create a release branch and modify `action.yaml` to point to the new image
+4. Open and merge a PR to add these changes to the default branch
+5. Make sure to fetch the new changes into your local repo: `$ git checkout main && git fetch origin && git merge origin main`
+6. Delete the `v1` tag locally and remotely: `$ git tag -d v1 && git push --delete origin v1`
+7. Create and push new tags: `$ git tag v1.7.0 && git tag v1 && git push origin --tags`
+8. Create the GitHub project release

action.yaml

@@ -13,9 +13,6 @@ inputs:
   minimum-approvals:
     description: Minimum number of approvals to progress workflow
     required: false
-  timeout-minutes:
-    description: Force timeout of your workflow pause
-    required: false
   issue-title:
     description: The custom subtitle for the issue
     required: false

main.go

@@ -29,6 +29,7 @@ func setActionOutput(name, value string) error {
 func handleInterrupt(ctx context.Context, client *github.Client, apprv *approvalEnvironment) {
 	newState := "closed"
 	closeComment := "Workflow cancelled, closing issue."
+
 	fmt.Println(closeComment)
 	_, _, err := client.Issues.CreateComment(ctx, apprv.targetRepoOwner, apprv.targetRepoName, apprv.approvalIssueNumber, &github.IssueComment{
 		Body: &closeComment,
@@ -65,7 +66,7 @@ func newCommentLoopChannel(ctx context.Context, apprv *approvalEnvironment, clie
 			switch approved {
 			case approvalStatusApproved:
 				newState := "closed"
-				closeComment := "All approvers have approved, continuing workflow and closing this issue."
+				closeComment := fmt.Sprintf("The required number of approvals (%d) has been met; continuing workflow and closing this issue.", apprv.minimumApprovals)
 				_, _, err := client.Issues.CreateComment(ctx, apprv.targetRepoOwner, apprv.targetRepoName, apprv.approvalIssueNumber, &github.IssueComment{
 					Body: &closeComment,
 				})