feat(deploy): add PR commenting feature (#3)

Add ability to automatically post/update a comment on PRs with the
deployment URL. This eliminates the need for a separate github-script
step in workflows.

New inputs:
- comment-on-pr: Enable PR commenting (default: false)
- github-token: Token with pull-requests:write permission
- comment-header: Custom header for the comment

Features:
- Upsert behavior: updates existing comment instead of creating duplicates
- Only runs on pull_request events
- Customizable comment header

Author: anneschuth

CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **deploy** action: PR commenting feature
+  - Automatically post/update a comment on PRs with the deployment URL
+  - New inputs: `comment-on-pr`, `github-token`, `comment-header`
+  - Upsert behavior: updates existing comment instead of creating duplicates
 - CI/CD pipeline with ShellCheck, actionlint, and yamllint
 - Branch protection and governance files (CODEOWNERS, issue templates, PR template)
 - CONTRIBUTING.md with development guidelines

deploy/README.md

@@ -14,6 +14,9 @@ Deploys a container image to ZAD Operations Manager.
 | `clone-from` | No | `''` | Clone configuration from existing deployment |
 | `force-clone` | No | `false` | Force clone even if deployment already exists |
 | `api-base-url` | No | `https://operations-manager.rig.prd1.gn2.quattro.rijksapps.nl/api` | ZAD Operations Manager API base URL |
+| `comment-on-pr` | No | `false` | Post/update a comment on the PR with the deployment URL |
+| `github-token` | No | `''` | GitHub token for PR commenting (needs `pull-requests: write`) |
+| `comment-header` | No | `## 🚀 Preview Deployment` | Custom header for the PR comment |
 
 ## Outputs
 
@@ -55,6 +58,42 @@ Deploys a container image to ZAD Operations Manager.
     clone-from: production
 ```
 
+### PR Preview with Automatic Comment
+
+Automatically post a comment on the PR with the deployment URL:
+
+```yaml
+deploy-preview:
+  runs-on: ubuntu-latest
+  if: github.event_name == 'pull_request'
+  permissions:
+    pull-requests: write
+  steps:
+    - name: Deploy PR Preview
+      uses: RijksICTGilde/zad-actions/deploy@v1
+      with:
+        api-key: ${{ secrets.ZAD_API_KEY }}
+        project-id: my-project
+        deployment-name: pr${{ github.event.pull_request.number }}
+        component: web
+        image: ghcr.io/org/app:pr-${{ github.event.number }}
+        clone-from: production
+        comment-on-pr: true
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+The action will create a comment like this on the PR:
+
+> ## 🚀 Preview Deployment
+>
+> Your changes have been deployed to a preview environment:
+>
+> **URL:** https://web-pr123-my-project.rig.prd1.gn2.quattro.rijksapps.nl
+>
+> This deployment will be automatically cleaned up when the PR is closed.
+
+On subsequent deployments to the same PR, the existing comment is updated instead of creating a new one.
+
 ### Use with GitHub Environment
 
 ```yaml
@@ -77,7 +116,17 @@ deploy:
 
 ## Permissions
 
-This action requires no special GitHub permissions. Only the ZAD API key is needed.
+| Feature | Required Permission |
+|---------|---------------------|
+| Basic deployment | None (only ZAD API key) |
+| PR commenting | `pull-requests: write` |
+
+For PR commenting, pass `github-token: ${{ secrets.GITHUB_TOKEN }}` and ensure your job has the required permission:
+
+```yaml
+permissions:
+  pull-requests: write
+```
 
 ## URL Pattern
 

deploy/action.yml

@@ -35,6 +35,18 @@ inputs:
     description: 'ZAD Operations Manager API base URL'
     required: false
     default: 'https://operations-manager.rig.prd1.gn2.quattro.rijksapps.nl/api'
+  comment-on-pr:
+    description: 'Post/update a comment on the PR with the deployment URL (requires github-token)'
+    required: false
+    default: 'false'
+  github-token:
+    description: 'GitHub token for PR commenting (needs pull-requests: write permission)'
+    required: false
+    default: ''
+  comment-header:
+    description: 'Custom header for the PR comment (default: "## 🚀 Preview Deployment")'
+    required: false
+    default: '## 🚀 Preview Deployment'
 
 outputs:
   url:
@@ -168,3 +180,45 @@ runs:
           echo "$BODY"
           exit 1
         fi
+
+    - name: Comment on PR
+      if: inputs.comment-on-pr == 'true' && inputs.github-token != '' && github.event_name == 'pull_request'
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.github-token }}
+        DEPLOYMENT_URL: ${{ steps.deploy.outputs.url }}
+        COMMENT_HEADER: ${{ inputs.comment-header }}
+        PR_NUMBER: ${{ github.event.pull_request.number }}
+        GITHUB_REPOSITORY: ${{ github.repository }}
+      run: |
+        # Build the comment body
+        COMMENT_BODY="${COMMENT_HEADER}
+
+        Your changes have been deployed to a preview environment:
+
+        **URL:** ${DEPLOYMENT_URL}
+
+        This deployment will be automatically cleaned up when the PR is closed."
+
+        # Check for existing comment from this action (identified by header)
+        EXISTING_COMMENT_ID=$(gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" \
+          --jq ".[] | select(.body | startswith(\"${COMMENT_HEADER}\")) | .id" \
+          2>/dev/null | head -n1 || echo "")
+
+        if [ -n "$EXISTING_COMMENT_ID" ]; then
+          # Update existing comment
+          echo "Updating existing PR comment (ID: $EXISTING_COMMENT_ID)"
+          gh api "repos/${GITHUB_REPOSITORY}/issues/comments/${EXISTING_COMMENT_ID}" \
+            -X PATCH \
+            -f body="$COMMENT_BODY" \
+            --silent
+          echo "PR comment updated"
+        else
+          # Create new comment
+          echo "Creating new PR comment"
+          gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" \
+            -X POST \
+            -f body="$COMMENT_BODY" \
+            --silent
+          echo "PR comment created"
+        fi