# This workflow checks if a PR requires documentation updates.

# It creates a Coder Agent chat session that uses AI to analyze the PR

# changes, search existing docs, and comment with recommendations.

#

# Uses the Coder Chat API (/api/experimental/chats) instead of the Tasks

# API — all API calls use curl + jq directly, no dedicated GitHub Action

# or workspace provisioning required.

#

# Triggers:

# - New PR opened: Initial documentation review

# - PR updated (synchronize): Re-review after changes

# - Label "doc-check" added: Manual trigger for review

# - PR marked ready for review: Review when draft is promoted

# - Workflow dispatch: Manual run with PR URL

#

# Note: This workflow requires access to secrets and will be skipped for:

# - Any PR where secrets are not available

# For these PRs, maintainers can manually trigger via workflow_dispatch.

name: AI Documentation Check

on:

pull_request:

types:

- opened

- synchronize

- labeled

- ready_for_review

workflow_dispatch:

inputs:

pr_url:

description: "Pull Request URL to check"

required: true

type: string

permissions:

contents: read

jobs:

doc-check:

name: Analyze PR for Documentation Updates Needed

runs-on: ubuntu-latest

# Run on: opened, synchronize, labeled (with doc-check label), ready_for_review, or workflow_dispatch

# Skip draft PRs unless manually triggered

if: |

(

github.event.action == 'opened' ||

github.event.action == 'synchronize' ||

github.event.label.name == 'doc-check' ||

github.event.action == 'ready_for_review' ||

github.event_name == 'workflow_dispatch'

) &&

(github.event.pull_request.draft == false || github.event_name == 'workflow_dispatch')

timeout-minutes: 30

env:

CODER_URL: ${{ secrets.DOC_CHECK_CODER_URL }}

CODER_SESSION_TOKEN: ${{ secrets.DOC_CHECK_CODER_SESSION_TOKEN }}

permissions:

contents: read

pull-requests: write

steps:

- name: Check if secrets are available

id: check-secrets

env:

CODER_URL: ${{ secrets.DOC_CHECK_CODER_URL }}

CODER_TOKEN: ${{ secrets.DOC_CHECK_CODER_SESSION_TOKEN }}

run: |

if [[ -z "${CODER_URL}" || -z "${CODER_TOKEN}" ]]; then

echo "skip=true" >> "${GITHUB_OUTPUT}"

echo "Secrets not available - skipping doc-check."

echo "This is expected for PRs where secrets are not available."

echo "Maintainers can manually trigger via workflow_dispatch if needed."

{

echo "⚠️ Workflow skipped: Secrets not available"

echo ""

echo "This workflow requires secrets that are unavailable for this run."

echo "Maintainers can manually trigger via workflow_dispatch if needed."

} >> "${GITHUB_STEP_SUMMARY}"

else

echo "skip=false" >> "${GITHUB_OUTPUT}"

fi

- name: Determine PR Context

if: steps.check-secrets.outputs.skip != 'true'

id: determine-context

env:

GITHUB_EVENT_NAME: ${{ github.event_name }}

GITHUB_EVENT_ACTION: ${{ github.event.action }}

GITHUB_EVENT_PR_HTML_URL: ${{ github.event.pull_request.html_url }}

GITHUB_EVENT_PR_NUMBER: ${{ github.event.pull_request.number }}

INPUTS_PR_URL: ${{ inputs.pr_url }}

run: |

# Determine trigger type for context

if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" ]]; then

echo "trigger_type=manual" >> "${GITHUB_OUTPUT}"

echo "Using PR URL: ${INPUTS_PR_URL}"

# Validate PR URL format

if [[ ! "${INPUTS_PR_URL}" =~ ^https://github\.com/[^/]+/[^/]+/pull/[0-9]+$ ]]; then

echo "::error::Invalid PR URL format: ${INPUTS_PR_URL}"

echo "::error::Expected format: https://github.com/owner/repo/pull/NUMBER"

exit 1

fi

ISSUE_URL="${INPUTS_PR_URL/\/pull\//\/issues\/}"

echo "pr_url=${ISSUE_URL}" >> "${GITHUB_OUTPUT}"

PR_NUMBER=$(echo "${INPUTS_PR_URL}" | grep -oP '(?<=pull/)\d+')

echo "pr_number=${PR_NUMBER}" >> "${GITHUB_OUTPUT}"

elif [[ "${GITHUB_EVENT_NAME}" == "pull_request" ]]; then

echo "Using PR URL: ${GITHUB_EVENT_PR_HTML_URL}"

ISSUE_URL="${GITHUB_EVENT_PR_HTML_URL/\/pull\//\/issues\/}"

echo "pr_url=${ISSUE_URL}" >> "${GITHUB_OUTPUT}"

echo "pr_number=${GITHUB_EVENT_PR_NUMBER}" >> "${GITHUB_OUTPUT}"

# Set trigger type based on action

case "${GITHUB_EVENT_ACTION}" in

opened)

echo "trigger_type=new_pr" >> "${GITHUB_OUTPUT}"

;;

synchronize)

echo "trigger_type=pr_updated" >> "${GITHUB_OUTPUT}"

;;

labeled)

echo "trigger_type=label_requested" >> "${GITHUB_OUTPUT}"

;;

ready_for_review)

echo "trigger_type=ready_for_review" >> "${GITHUB_OUTPUT}"

;;

*)

echo "trigger_type=unknown" >> "${GITHUB_OUTPUT}"

;;

esac

else

echo "::error::Unsupported event type: ${GITHUB_EVENT_NAME}"

exit 1

fi

- name: Build chat prompt

if: steps.check-secrets.outputs.skip != 'true'

id: extract-context

env:

PR_NUMBER: ${{ steps.determine-context.outputs.pr_number }}

TRIGGER_TYPE: ${{ steps.determine-context.outputs.trigger_type }}

run: |

echo "Analyzing PR #${PR_NUMBER} (trigger: ${TRIGGER_TYPE})"

# Build context based on trigger type

case "${TRIGGER_TYPE}" in

new_pr)

CONTEXT="This is a NEW PR. Perform initial documentation review."

;;

pr_updated)

CONTEXT="This PR was UPDATED with new commits. Check if previous feedback was addressed or if new doc needs arose."

;;

label_requested)

CONTEXT="A documentation review was REQUESTED via label. Perform a thorough review."

;;

ready_for_review)

CONTEXT="This PR was marked READY FOR REVIEW. Perform a thorough review."

;;

manual)

CONTEXT="This is a MANUAL review request. Perform a thorough review."

;;

*)

CONTEXT="Perform a documentation review."

;;

esac

# Build chat prompt with sticky comment logic

CHAT_PROMPT="Use the doc-check skill to review PR #${PR_NUMBER} in coder/coder.

${CONTEXT}

Use \`gh\` to get PR details, diff, and all comments. Look for an existing doc-check comment containing \`<!-- doc-check-sticky -->\` - if one exists, you'll update it instead of creating a new one.

**Do not comment if no documentation changes are needed.**

If a sticky comment already exists, compare your current findings against it:

- Check off \`[x]\` items that are now addressed

- Strikethrough items no longer needed (e.g., code was reverted)

- Add new unchecked \`[ ]\` items for newly discovered needs

- If an item is checked but you can't verify the docs were added, add a warning note below it

- If nothing meaningful changed, don't update the comment at all

## Comment format

Use this structure (only include relevant sections):

\`\`\`

## Documentation Check

### Updates Needed

- [ ] \`docs/path/file.md\` - What needs to change

- [x] \`docs/other/file.md\` - This was addressed

- ~~\`docs/removed.md\` - No longer needed~~ *(reverted in abc123)*

### New Documentation Needed

- [ ] \`docs/suggested/path.md\` - What should be documented

> ⚠️ *Checked but no corresponding documentation changes found in this PR*

---

*Automated review via [Coder Agents](https://coder.com/docs/ai-coder/agents)*

<!-- doc-check-sticky -->

\`\`\`

The \`<!-- doc-check-sticky -->\` marker must be at the end so future runs can find and update this comment."

# Output the prompt

{

echo "chat_prompt<<EOFOUTPUT"

echo "${CHAT_PROMPT}"

echo "EOFOUTPUT"

} >> "${GITHUB_OUTPUT}"

# ------------------------------------------------------------------

# Create a chat via the Coder Chat API.

# The Chat API creates a lightweight chat session — no workspace

# provisioning or dedicated GitHub Action checkout required.

# ------------------------------------------------------------------

- name: Create chat via Coder Chat API

if: steps.check-secrets.outputs.skip != 'true'

id: create-chat

continue-on-error: true

env:

CHAT_PROMPT: ${{ steps.extract-context.outputs.chat_prompt }}

run: |

set -euo pipefail

echo "Creating chat session..."

RESPONSE=$(curl --silent --fail-with-body \

-X POST \

-H "Coder-Session-Token: ${CODER_SESSION_TOKEN}" \

-H "Content-Type: application/json" \

-d "$(jq -n --arg prompt "${CHAT_PROMPT}" \

'{content: [{type: "text", text: $prompt}]}')" \

"${CODER_URL}/api/experimental/chats")

CHAT_ID=$(echo "${RESPONSE}" | jq -r '.id')

CHAT_STATUS=$(echo "${RESPONSE}" | jq -r '.status')

if [[ -z "${CHAT_ID}" || "${CHAT_ID}" == "null" ]]; then

echo "::error::Failed to create chat — no ID returned"

echo "Response: ${RESPONSE}"

exit 1

fi

# Validate that CHAT_ID is a UUID before using it in URL paths.

if [[ ! "${CHAT_ID}" =~ ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ ]]; then

echo "::error::CHAT_ID is not a valid UUID: ${CHAT_ID}"

exit 1

fi

CHAT_URL="${CODER_URL}/agents?chat=${CHAT_ID}"

echo "Chat created: ${CHAT_ID} (status: ${CHAT_STATUS})"

echo "Chat URL: ${CHAT_URL}"

echo "chat_id=${CHAT_ID}" >> "${GITHUB_OUTPUT}"

echo "chat_url=${CHAT_URL}" >> "${GITHUB_OUTPUT}"

- name: Handle Chat Creation Failure

if: steps.check-secrets.outputs.skip != 'true' && steps.create-chat.outcome != 'success'

run: |

{

echo "## Documentation Check"

echo ""

echo "⚠️ The Coder Chat API was unavailable, so this"

echo "advisory documentation check did not run."

echo ""

echo "Maintainers can rerun the workflow or trigger it manually"

echo "after the service recovers."

} >> "${GITHUB_STEP_SUMMARY}"

- name: Write Chat Info

if: steps.check-secrets.outputs.skip != 'true' && steps.create-chat.outcome == 'success'

env:

CHAT_ID: ${{ steps.create-chat.outputs.chat_id }}

CHAT_URL: ${{ steps.create-chat.outputs.chat_url }}

PR_URL: ${{ steps.determine-context.outputs.pr_url }}

run: |

{

echo "## Documentation Check"

echo ""

echo "**PR:** ${PR_URL}"

echo "**Chat ID:** \`${CHAT_ID}\`"

echo "**Chat URL:** ${CHAT_URL}"

echo ""

} >> "${GITHUB_STEP_SUMMARY}"

# ------------------------------------------------------------------

# Poll the chat status until the agent finishes.

# The Chat API is asynchronous — after creation the agent begins

# working in the background. We poll GET /api/experimental/chats/<id>

# every 5 seconds until the status is "waiting" (agent needs input),

# "completed" (agent finished), or "error". Timeout after 10 minutes.

# ------------------------------------------------------------------

- name: Poll chat status

if: steps.check-secrets.outputs.skip != 'true' && steps.create-chat.outcome == 'success'

id: poll-status

env:

CHAT_ID: ${{ steps.create-chat.outputs.chat_id }}

run: |

set -euo pipefail

POLL_INTERVAL=5

TIMEOUT=600

ELAPSED=0

echo "Polling chat ${CHAT_ID} every ${POLL_INTERVAL}s (timeout: ${TIMEOUT}s)..."

while true; do

RESPONSE=$(curl --silent --fail-with-body \

-H "Coder-Session-Token: ${CODER_SESSION_TOKEN}" \

"${CODER_URL}/api/experimental/chats/${CHAT_ID}")

STATUS=$(echo "${RESPONSE}" | jq -r '.status')

echo "[${ELAPSED}s] Chat status: ${STATUS}"

case "${STATUS}" in

waiting|completed)

echo "Chat reached terminal status: ${STATUS}"

echo "final_status=${STATUS}" >> "${GITHUB_OUTPUT}"

exit 0

;;

error)

echo "::error::Chat entered error state"

echo "${RESPONSE}" | jq .

echo "final_status=error" >> "${GITHUB_OUTPUT}"

exit 1

;;

pending|running)

# Still working — keep polling.

;;

*)

echo "::warning::Unknown chat status: ${STATUS}"

;;

esac

if [[ ${ELAPSED} -ge ${TIMEOUT} ]]; then

echo "::error::Timed out after ${TIMEOUT}s waiting for chat to finish"

echo "final_status=timeout" >> "${GITHUB_OUTPUT}"

exit 1

fi

sleep "${POLL_INTERVAL}"

ELAPSED=$((ELAPSED + POLL_INTERVAL))

done

- name: Write Final Summary

if: always() && steps.check-secrets.outputs.skip != 'true'

env:

CREATE_CHAT_OUTCOME: ${{ steps.create-chat.outcome }}

CHAT_ID: ${{ steps.create-chat.outputs.chat_id }}

CHAT_URL: ${{ steps.create-chat.outputs.chat_url }}

FINAL_STATUS: ${{ steps.poll-status.outputs.final_status }}

PR_NUMBER: ${{ steps.determine-context.outputs.pr_number }}

run: |

{

echo ""

echo "---"

echo "### Result"

echo ""

if [[ "${CREATE_CHAT_OUTCOME}" == "success" ]]; then

echo "**Status:** ${FINAL_STATUS:-Chat completed}"

echo "**Chat URL:** ${CHAT_URL}"

echo ""

echo "Chat \`${CHAT_ID}\` has finished."

else

echo "**Status:** Skipped because the Coder Chat API"

echo "was unavailable."

fi

} >> "${GITHUB_STEP_SUMMARY}"