add_pr_comment.md

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:

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:

on:
  pull_request:
jobs:
  octodns-sync:
    name: Run `octodns-sync` with public.yaml
    runs-on: ubuntu-20.04
    outputs:
      plan: ${{ steps.generate-plan.outputs.plan }}
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: '3.10'
      - run: pip install -r requirements.txt
      - uses: solvaholic/octodns-sync@main
        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-20.04
    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:

on:
  pull_request:
jobs:
  test:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: '3.10'
      - run: pip install -r requirements.txt
      - uses: solvaholic/octodns-sync@main
        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 ☝️ all this and improving solvaholic/octodns-sync 🙇