chore: update docs workflow

[mcstepp]

What does this PR do?

1. Docs Path Filter (job_detect_changes.yaml)

• Changed from: apps/docs/, apps/engineering/, .md, README, CHANGELOG*
• Changed to: apps/docs/** only
• Removed global markdown file triggers (root .md, README, CHANGELOG*)
• Removed apps/engineering/** from docs filter (engineering gets it own flow, won't need mintlify)
• Added comment clarifying .md files ARE content when inside apps/docs

2. Mintlify Deployment (deploy.yaml)

• Changed dependency from api_production_deployment to detect_changes
• Added condition: if: needs.detect_changes.outputs.docs == 'true'
• Docs now deploy independently (no longer waits for API)
• Docs only deploy when apps/docs/** changes

Impact:

• Docs workflows now isolated: Run only when apps/docs/** files change
• Faster docs deployments: No longer wait for API production deployment
• Proper scoping: Root README.md, CHANGELOG.md changes won't trigger docs workflows
• Content-aware: .md files inside apps/docs/ correctly trigger workflows (they're content, not meta files)

Fixes #4156

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Chore (refactoring code, technical debt, workflow improvements)
• Enhancement (small improvements)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How should this be tested?

Scenario 1: Doc change in apps/docs (happy path) #4218

1. Go to Checks tab
2. Under PR section, expand "detect changes"
3. Verify that output = ["docs", "workflow"] (workflow because it contains the workflow changes for the test workflow to run)
4. Verify Build, API, Go API, and Dashboard checks are skipped

Scenario 2: Doc change in Dashboard #4219

1. Go to Checks tab
2. Under PR section, expand "detect changes"
3. Verify that output = ["workflow"] (workflow because it contains the workflow changes for the test workflow to run)
4. Verify Build, API, Go API, Dashboard, and Mintlify checks are skipped

Scenario 3: Root doc change #4220

1. Go to Checks tab
2. Under PR section, expand "detect changes"
3. Verify that output = ["workflow"] (workflow because it contains the workflow changes for the test workflow to run)
4. Verify Build, API, Go API, Dashboard, and Mintlify checks are skipped

Checklist

Required

• Filled out the "How to test" section in this PR
• Read Contributing Guide
• Self-reviewed my own code
• Commented on my code in hard-to-understand areas
• Ran pnpm build
• Ran pnpm fmt
• Ran make fmt on /go directory
• Checked for warnings, there are none
• Removed all console.logs
• Merged the latest changes from main onto my branch with git pull origin main
• My changes don't cause any responsiveness issues

Appreciated

• If a UI change was made: Added a screen recording or screenshots to this PR
• Updated the Unkey Docs if changes were necessary

[linear]

ENG-2148 [APPS] [P1] Docs Workflow

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1495883

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
dashboard	Ready	Preview	Comment	Nov 5, 2025 5:37pm
engineering	Ready	Preview	Comment	Nov 5, 2025 5:37pm

[coderabbitai]

📝 Walkthrough

Walkthrough

GitHub Actions workflows are updated to gate Mintlify documentation deployment on file changes within apps/docs/. The job_detect_changes workflow now exclusively monitors apps/docs/**, while deploy.yaml ties mintlify_deployment to the docs detection output.

Changes

Cohort / File(s)	Summary
Docs workflow dependency and gating .github/workflows/deploy.yaml	mintlify_deployment job modified to depend on detect_changes instead of api_production_deployment with conditional execution gating: runs only when needs.detect_changes.outputs.docs == 'true'
Docs path filter refinement .github/workflows/job_detect_changes.yaml	Docs path filter narrowed from multi-pattern match to single filter apps/docs/**; removed patterns for apps/engineering/**, *.md, README*, CHANGELOG*; added clarifying comment about .md files being content

Sequence Diagram

sequenceDiagram
    autonumber
    actor Push
    participant detect_changes as detect_changes Job
    participant mintlify as mintlify_deployment Job
    
    Push->>detect_changes: Trigger workflow
    detect_changes->>detect_changes: Check path filters
    alt files in apps/docs/**
        detect_changes->>detect_changes: Set outputs.docs = 'true'
    else other paths
        detect_changes->>detect_changes: Set outputs.docs = 'false'
    end
    
    detect_changes-->>mintlify: Complete
    alt outputs.docs == 'true'
        mintlify->>mintlify: Execute deployment
    else outputs.docs == 'false'
        mintlify->>mintlify: Skip (conditional gate)
    end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

• Review the path filter refinement to confirm no legitimate docs-related files are excluded by narrowing from multi-pattern to single apps/docs/** filter
• Verify the conditional logic needs.detect_changes.outputs.docs == 'true' correctly gates the Mintlify deployment and doesn't break existing workflows

Possibly related issues

• [APPS] [P1] Docs Workflow #4156 — These changes directly implement the acceptance criteria to trigger Mintlify deployment only on apps/docs/** changes with .md files treated as content

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title is vague and generic, using 'update docs workflow' without clearly specifying the main change or impact of the updates.	Consider a more specific title like 'chore: isolate docs workflow to apps/docs changes only' to better convey the primary change.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description check	✅ Passed	The PR description is comprehensive and well-structured, covering changes, impact, testing scenarios, and completed checklist items against the template requirements.
Linked Issues check	✅ Passed	The code changes align with issue #4156 requirements: docs filter restricted to apps/docs/**, mintlify deployment conditioned on detect_changes.outputs.docs, and workflows now isolated without dependency triggers.
Out of Scope Changes check	✅ Passed	All changes are directly related to issue #4156 objectives: workflow filter updates and deployment dependency changes. No unrelated modifications detected.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch ENG-2148-docs-workflow

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f9d581d and 152325b.

📒 Files selected for processing (2)

• .github/workflows/deploy.yaml (1 hunks)
• .github/workflows/job_detect_changes.yaml (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Analyze (javascript-typescript)

🔇 Additional comments (2)

.github/workflows/job_detect_changes.yaml (1)

115-117: Path filter narrowing correctly implements docs isolation.

The docs filter now exclusively monitors apps/docs/**, removing broader patterns (apps/engineering/**, *.md, README*, CHANGELOG*). The comment clarifies that markdown files within the docs directory are treated as content and will trigger workflows—precisely as intended per PR objectives. The narrowing ensures docs workflows skip changes to root-level metadata files.

.github/workflows/deploy.yaml (1)

66-68: Docs deployment correctly decoupled and gated on change detection.

The mintlify_deployment job now depends solely on detect_changes (rather than the API production pipeline) and runs conditionally only when docs == 'true'. This properly decouples documentation deployment, allowing it to proceed independently of API deployment cycles while remaining gated to actual apps/docs/** changes. The output reference correctly maps to the docs output defined in job_detect_changes.yaml.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Thank you for following the naming conventions for pull request titles! 🙏

[graphite-app]

[graphite-app]

Graphite Automations

"Post a GIF when PR approved" took an action on this PR • (11/05/25)

1 gif was posted to this PR based on Andreas Thomas's automation.