fix: gracefully handle missing DOCS_PREVIEW_DEPLOY_KEY secret

[JacobCoffee]

Summary

• Fixes authentication failure in docs preview deployment workflow (#19617745585)
• Adds token existence check before attempting deployment
• Gracefully skips deployment when secret is not configured
• Posts informative PR comment explaining the issue

Changes

• Added Check if deploy token exists step to validate secret presence
• Made deployment step conditional on token availability
• Added alternative PR comment for when deployment is skipped
• Prevents workflow failure cascade from missing/invalid secret

Root Cause

The workflow was failing because DOCS_PREVIEW_DEPLOY_KEY secret is either:

• Not configured in repository secrets
• Invalid or expired
• Lacks write permissions to byte-docs-preview repository

Test Plan

• Workflow succeeds when secret is missing (skips deployment)
• Workflow succeeds when secret is valid (deploys normally)
• Appropriate PR comment is posted in both scenarios

Post-Merge Action Required

Repository administrator needs to configure DOCS_PREVIEW_DEPLOY_KEY secret:

1. Create Personal Access Token with repo scope
2. Add as repository secret: Settings → Secrets → Actions → New repository secret
3. Name: DOCS_PREVIEW_DEPLOY_KEY
4. Value: Generated PAT

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

[sourcery-ai]

Sorry @JacobCoffee, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[railway-app]

🚅 Deployed to the byte-pr-127 environment in byte

Service	Status	Web	Updated (UTC)
byte	◻️ Removed (View Logs)	Web	Nov 23, 2025 at 10:06 pm

[JacobCoffee]

✅ Docs Preview Repository Created

The byte-docs-preview repository has been set up and is ready to host documentation preview builds:

• Repository: https://github.com/JacobCoffee/byte-docs-preview
• GitHub Pages: https://jacobcoffee.github.io/byte-docs-preview/ (active)
• Auto-cleanup: Daily workflow to remove closed PR previews

Setup Complete

✅ Repository created with proper structure
✅ Cleanup automation configured (remove_stale.py + workflow)
✅ GitHub Pages enabled on gh-pages branch
✅ Documentation and README added

Required Action: Configure Deploy Token

To enable documentation preview deployments, you need to create a Personal Access Token:

Step 1: Generate Token

1. Go to https://github.com/settings/tokens/new
2. Token name: Byte Docs Preview Deploy
3. Expiration: No expiration (or set to your preference)
4. Scopes: Select repo (Full control of private repositories)
5. Click Generate token
6. Copy the token (you won't be able to see it again!)

Step 2: Add Token to Secrets

1. Go to https://github.com/JacobCoffee/byte/settings/secrets/actions
2. Click New repository secret
3. Name: DOCS_PREVIEW_DEPLOY_KEY
4. Value: Paste the token you copied
5. Click Add secret

Verification

Once the token is configured, you can verify the setup by:

1. Opening a test PR in the main repository
2. The CI workflow should build docs and deploy to byte-docs-preview
3. A comment will appear on the PR with the preview URL
4. Preview URL format: https://jacobcoffee.github.io/byte-docs-preview/{PR_NUMBER}

Architecture

This follows the same pattern as Litestar's polyfactory-docs-preview:

• Separate repository for hosting previews (keeps main repo clean)
• Automated daily cleanup of stale previews
• Simple GitHub Pages deployment
• No external dependencies or services

The workflow will now gracefully handle missing tokens and post informative comments to PRs.