|
| 1 | +// Docs preview gate and PR comment. .github/workflows/docs-preview.yml wires |
| 2 | +// these up: `authorize` decides whether a run may build and deploy a preview |
| 3 | +// (and for which commit), `comment` reports the outcome on the pull request. |
| 4 | +// The security model is described in the workflow's header. |
| 5 | +'use strict'; |
| 6 | + |
| 7 | +const MARKER = '<!-- docs-preview -->'; |
| 8 | +const BOT_LOGIN = 'github-actions[bot]'; |
| 9 | + |
| 10 | +// Sets the job outputs `authorized`, `pr_number`, `head_sha` and |
| 11 | +// `slash_attempt` for a pull_request_target or /preview-docs issue_comment run. |
| 12 | +async function authorize({ github, context, core }) { |
| 13 | + const { owner, repo } = context.repo; |
| 14 | + |
| 15 | + async function permissionFor(username) { |
| 16 | + const { data } = await github.rest.repos.getCollaboratorPermissionLevel({ owner, repo, username }); |
| 17 | + return { level: data.permission, role: data.role_name }; |
| 18 | + } |
| 19 | + |
| 20 | + let authorized = false; |
| 21 | + let prNumber = ''; |
| 22 | + let headSha = ''; |
| 23 | + let slashAttempt = false; |
| 24 | + |
| 25 | + if (context.eventName === 'pull_request_target') { |
| 26 | + const pr = context.payload.pull_request; |
| 27 | + prNumber = String(pr.number); |
| 28 | + headSha = pr.head.sha; |
| 29 | + // No automatic preview for fork PRs: actions/checkout refuses to fetch a |
| 30 | + // fork's head in a pull_request_target run. A maintainer can still request |
| 31 | + // one with /preview-docs. (head.repo is null once the fork is deleted.) |
| 32 | + const headRepo = pr.head.repo; |
| 33 | + if (!headRepo || headRepo.id !== context.payload.repository.id) { |
| 34 | + core.info(`PR #${prNumber} head is on ${headRepo ? headRepo.full_name : 'a deleted fork'}; fork PRs are previewed via /preview-docs only.`); |
| 35 | + } else { |
| 36 | + // Gate on the *sender* (whoever caused this run — on synchronize that |
| 37 | + // is the pusher), not the PR author, so a non-admin pushing to an |
| 38 | + // admin-opened branch does not get an automatic build. |
| 39 | + const actor = context.payload.sender.login; |
| 40 | + const perm = await permissionFor(actor); |
| 41 | + authorized = perm.level === 'admin'; |
| 42 | + core.info(`pull_request_target by ${actor} (level=${perm.level}, role=${perm.role}) → authorized=${authorized}`); |
| 43 | + } |
| 44 | + } else { |
| 45 | + // issue_comment: the job-level `if:` already guarantees this is a PR |
| 46 | + // comment starting with /preview-docs. |
| 47 | + slashAttempt = true; |
| 48 | + const actor = context.payload.comment.user.login; |
| 49 | + prNumber = String(context.payload.issue.number); |
| 50 | + const perm = await permissionFor(actor); |
| 51 | + authorized = perm.level === 'admin' || perm.role === 'maintain'; |
| 52 | + if (authorized) { |
| 53 | + const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: Number(prNumber) }); |
| 54 | + if (pr.state !== 'open') { |
| 55 | + authorized = false; |
| 56 | + core.info(`PR #${prNumber} is ${pr.state}; refusing to preview.`); |
| 57 | + } else { |
| 58 | + headSha = pr.head.sha; |
| 59 | + } |
| 60 | + } |
| 61 | + core.info(`/preview-docs by ${actor} (level=${perm.level}, role=${perm.role}) → authorized=${authorized}`); |
| 62 | + } |
| 63 | + |
| 64 | + core.setOutput('authorized', String(authorized)); |
| 65 | + core.setOutput('pr_number', prNumber); |
| 66 | + core.setOutput('head_sha', headSha); |
| 67 | + core.setOutput('slash_attempt', String(slashAttempt)); |
| 68 | +} |
| 69 | + |
| 70 | +// Posts or updates the preview comment on the PR. Reads the outcome of the |
| 71 | +// earlier jobs from the step's env: AUTHORIZED, PR_NUMBER, HEAD_SHA, |
| 72 | +// DEPLOY_RESULT, DEPLOYMENT_URL, ALIAS_URL, RUN_URL. |
| 73 | +async function comment({ github, context }) { |
| 74 | + const { owner, repo } = context.repo; |
| 75 | + const env = process.env; |
| 76 | + const issue_number = Number(env.PR_NUMBER); |
| 77 | + |
| 78 | + async function upsert(body) { |
| 79 | + const comments = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number, per_page: 100 }); |
| 80 | + const existing = comments.find((c) => c.user?.login === BOT_LOGIN && c.body?.includes(MARKER)); |
| 81 | + if (existing) { |
| 82 | + await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body }); |
| 83 | + } else { |
| 84 | + await github.rest.issues.createComment({ owner, repo, issue_number, body }); |
| 85 | + } |
| 86 | + } |
| 87 | + |
| 88 | + if (env.AUTHORIZED !== 'true') { |
| 89 | + await github.rest.issues.createComment({ |
| 90 | + owner, repo, issue_number, |
| 91 | + body: `@${context.actor} — only repository admins or maintainers can run \`/preview-docs\` (and the PR must be open).`, |
| 92 | + }); |
| 93 | + return; |
| 94 | + } |
| 95 | + |
| 96 | + if (env.DEPLOY_RESULT !== 'success') { |
| 97 | + await upsert( |
| 98 | + `${MARKER}\n### 📚 Documentation preview\n\n` + |
| 99 | + `❌ Preview build **failed** for \`${env.HEAD_SHA.slice(0, 7)}\` — [workflow logs](${env.RUN_URL}).` |
| 100 | + ); |
| 101 | + return; |
| 102 | + } |
| 103 | + |
| 104 | + const previewUrl = env.ALIAS_URL || env.DEPLOYMENT_URL; |
| 105 | + const ts = new Date().toISOString().replace('T', ' ').replace(/\.\d+Z$/, ' UTC'); |
| 106 | + await upsert( |
| 107 | + `${MARKER}\n### 📚 Documentation preview\n\n` + |
| 108 | + `| | |\n|---|---|\n` + |
| 109 | + `| **Preview** | ${previewUrl} |\n` + |
| 110 | + `| **Deployment** | ${env.DEPLOYMENT_URL} |\n` + |
| 111 | + `| **Commit** | \`${env.HEAD_SHA.slice(0, 7)}\` |\n` + |
| 112 | + `| **Triggered by** | @${context.actor} |\n` + |
| 113 | + `| **Updated** | ${ts} |\n` |
| 114 | + ); |
| 115 | +} |
| 116 | + |
| 117 | +module.exports = { authorize, comment }; |
0 commit comments