Create add_pr_comment.md

docs/add_pr_comment.md

@@ -0,0 +1,104 @@
+# Add the `octodns-sync` plan output to a pull request comment
+
+When a user proposes DNS configuration changes in a pull request, it may help to write the `octodns-sync` plan output to a comment in the pull request.
+
+This document describes two approaches for achieving this. Be aware that, for either approach, if users will propose DNS changes in pull requests **from forks** then it may be necessary to work around some GitHub token permission constraints.
+
+When using this Action's built-in `add_pr_comment` feature, be aware it'll add a new comment for each run. To avoid creating a new comment for each run, and/or to get more control over the contents of the comment, use @peter-evans' [`create-or-update-comment` Action] instead.
+
+In either case, 1) set `plan_outputs` in the **octodns** configuration and 2) configure the workflow to add a pull request comment.
+
+## Configure octodns
+
+To make the `octodns-sync` plan available, configure [`plan_outputs` in the **octodns** configuration], for example `public.yaml`:
+
+```yaml
+manager:
+  plan_outputs:
+    html:
+      class: octodns.provider.plan.PlanHtml
+```
+
+## Configure the workflow
+
+_Note: If users will propose DNS changes in pull requests **from forks** then it may be necessary to work around some GitHub token permission constraints._
+
+### @peter-evans' `create-or-update-comment` Action
+
+Using this approach gives full control over the comment that's added to the pull request. For example: Customize header and footer text in the comment body, and update the existing plan comment rather than add a new comment each time.
+
+Generally there are three steps: 1) Run `octodns-sync` to generate the plan output, 2) find the pull request comment to be updated, if it already exists, and 3) create or update the pull request comment with the current plan output.
+
+This example workflow illustrates one way to perform those steps:
+
+```yaml
+on:
+  pull_request:
+jobs:
+  octodns-sync:
+    name: Run `octodns-sync` with public.yaml
+    runs-on: ubuntu-latest
+    outputs:
+      plan: ${{ steps.generate-plan.outputs.plan }}
+    steps:
+      - uses: actions/checkout@v2
+      - uses: solvaholic/octodns-sync@v2.3.0
+        id: generate-plan
+        with:
+          config_path: public.yaml
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.route53_aws_key_id }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.route53_aws_secret_access_key }}
+  add-pr-comment:
+    name: Add `octodns-sync` plan to comment
+    needs: [octodns-sync]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Find previous comment, if present
+        uses: peter-evans/find-comment@v1.2.0
+        id: fc
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: github-actions[bot]
+          body-includes: Automatically generated by octodns-sync
+      - name: Create or update comment
+        id: prcomment
+        uses: peter-evans/create-or-update-comment@v1.4.5
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-id: ${{ steps.fc.outputs.comment-id }}
+          body: |
+            ## OctoDNS Plan for `${{ github.ref }}`
+      
+            ${{ needs.octodns-sync.outputs.plan }}
+
+            Automatically generated by octodns-sync
+          edit-mode: replace
+```
+
+### Built-in `add_pr_comment` feature
+
+Using this approach is simple: Set the `add_pr_comment` input to 'Yes' and provide a token authorized to comment on the pull request. For example, this will add the `octodns-sync` plan output to a new comment each time the workflow runs:
+
+```yaml
+on:
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: solvaholic/octodns-sync@v2.3.0
+        with:
+          config_path: public.yaml
+          add_pr_comment: 'Yes'
+          pr_comment_token: '${{ github.token }}'
+```
+
+## Thank you
+
+Thank you @xt0rted @patcon @travislikestocode @thattommyhall for your help and support sorting :point_up: all this and improving **solvaholic/octodns-sync** :bow:
+
+
+[`create-or-update-comment` Action]: https://github.com/peter-evans/create-or-update-comment
+[`plan_outputs` in the **octodns** configuration]: https://github.com/octodns/octodns/pull/156