# 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.

#

# 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') &&

(github.event_name == 'workflow_dispatch' || github.event.pull_request.head.repo.full_name == github.repository)

timeout-minutes: 30

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: Check the review workspace is usable

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

id: check-workspace

env:

CODER_URL: ${{ secrets.DOC_CHECK_CODER_URL }}

CODER_TOKEN: ${{ secrets.DOC_CHECK_CODER_SESSION_TOKEN }}

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

run: |

# A review reuses one chat per PR, and that chat owns one workspace.

# The workspace stops after about a day and then goes dormant. A chat

# cannot repair a dormant workspace: start_workspace and

# create_workspace both fail with

# "unauthorized: rbac: forbidden". The review then reads

# nothing and posts nothing, and this job used to still pass. Fail

# here instead, so the check reports what happened.

# https://linear.app/codercom/issue/CODAGT-1025

WS_NAME="doc-check-pr-${PR_NUMBER}"

RESPONSE=$(curl -sS --fail-with-body -G \

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

--data-urlencode "q=owner:me name:${WS_NAME}" \

"${CODER_URL%/}/api/v2/workspaces") || {

echo "::warning::Could not read the workspace state from Coder. Continuing."

exit 0

}

DORMANT_AT=$(echo "${RESPONSE}" | jq -r '.workspaces[0].dormant_at // empty')

if [[ -n "${DORMANT_AT}" ]]; then

echo "::error::${WS_NAME} is dormant since ${DORMANT_AT}. The review cannot run, because a chat cannot start its own dormant workspace: https://linear.app/codercom/issue/CODAGT-1025"

{

echo "### Documentation check did not run"

echo ""

echo "The workspace \`${WS_NAME}\` is dormant since ${DORMANT_AT}."

echo ""

echo "A chat cannot start its own dormant workspace, so the review would read no files and post no comment. See [CODAGT-1025](https://linear.app/codercom/issue/CODAGT-1025)."

echo ""

echo "To run the review now, start \`${WS_NAME}\` in Coder, then push again or re-run this job."

} >> "${GITHUB_STEP_SUMMARY}"

exit 1

fi

echo "Workspace state is usable."

- 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 the chat prompt. Durable rules live in the skill

# (.claude/skills/doc-check/SKILL.md), so this prompt stays short

# and carries only what changes per run.

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

${CONTEXT}

Use \`gh\` to read the PR details, the diff, and every comment.

Follow the skill in full: its evidence discipline, its comment

rules, and its comment format. **Do not comment if no

documentation changes are needed.**

## When the workspace is broken

A tool call that fails with \`unauthorized: rbac: forbidden\` is an

infrastructure state, not a bad command, so retrying the same

command changes nothing.

Call \`start_workspace\` with no arguments. If it answers

\`workspace was deleted\` or \`chat has no workspace\`, call

\`list_templates\` for the \`coder-workflow-bot\` template ID, then

\`create_workspace\` with it, and run the failed call again. If it

answers \`load workspace: unauthorized: rbac: forbidden\`, the

workspace is dormant and you cannot repair it: stop, say you could

not review the PR, and name the error. Post no comment, and do not

imply the docs are fine, because you did not read them.

Create any new workspace from the \"coder-workflow-bot\" template."

# Output the prompt

{

echo "chat_prompt<<EOFOUTPUT"

echo "${CHAT_PROMPT}"

echo "EOFOUTPUT"

} >> "${GITHUB_OUTPUT}"

- name: Run doc-check via Coder Agent Chat

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

uses: coder/agents-chat-action@b3fc81d7dae5006dd124e98ef6fada1a36cdd86e # v0.3.0

with:

coder-url: ${{ secrets.DOC_CHECK_CODER_URL }}

coder-token: ${{ secrets.DOC_CHECK_CODER_SESSION_TOKEN }}

# The bot account belongs to many organizations on this deployment,

# where the action's fallback organization choice is not

# deterministic. Pin it, because a model configuration ID only

# resolves inside its own organization.

coder-organization: coder

# Pins the model that reviews the PR. Set this repository variable to

# a model configuration ID in the organization above. Unset means the

# deployment's default model, so clearing the variable is the

# rollback path and needs no code change.

model-config-id: ${{ vars.DOC_CHECK_MODEL_CONFIG_ID }}

chat-prompt: ${{ steps.extract-context.outputs.chat_prompt }}

github-url: ${{ steps.determine-context.outputs.pr_url }}

github-token: ${{ github.token }}

wait: complete

wait-timeout-seconds: "600"

# The doc-check agent posts its own sticky comment when there

# are findings; failures surface in the workflow run log.

comment-on-issue: "false"