gh-netresearch-claude-code-marketplace-skills-typo3-docs/references/intercept-deployment.md

TYPO3 Intercept Deployment & Webhook Setup

Complete guide for setting up automatic documentation deployment using TYPO3 Intercept webhooks.

Overview

TYPO3 Intercept provides automatic documentation rendering and publishing for TYPO3 extensions. When properly configured, your documentation is automatically built and published to docs.typo3.org whenever you push commits or create version tags.

Prerequisites

Before setting up webhooks, ensure:

1. Extension Published in TER: Your extension must be registered in the TYPO3 Extension Repository (TER) with the same extension key specified in composer.json
2. Git Repository Referenced: The Git repository URL must be listed on your extension's TER detail page
3. Documentation Structure: Your Documentation/ directory must contain:
   • Index.rst (main entry point)
   • Settings.cfg (documentation metadata)
   • Valid RST files following TYPO3 documentation standards

Webhook Registration

GitHub Setup

1. Navigate to Repository Settings

   • Go to your GitHub repository
   • Click Settings → Webhooks
   • Click Add webhook

2. Configure Webhook

   • Payload URL: https://docs-hook.typo3.org
   • Content type: application/json
   • SSL verification: Enable SSL verification
   • Which events: Select "Just the push event"
   • Active: Check the "Active" checkbox

3. Save Webhook

   • Click Add webhook to save
   • GitHub will send a test ping to verify connectivity

GitLab Setup

1. Navigate to Webhooks

   • Go to your GitLab project
   • Click Settings → Webhooks

2. Configure Webhook

   • URL: https://docs-hook.typo3.org
   • Trigger: Check both:
     • Push events
     • Tag push events
   • SSL verification: Enable SSL verification

3. Add Webhook

   • Click Add webhook to save
   • GitLab will test the connection

First-Time Approval

The first time you trigger documentation rendering, the TYPO3 Documentation Team must approve your repository:

1. Automatic Hold: First webhook trigger is automatically placed on hold
2. Manual Review: Documentation Team reviews:
   • TER registration matches composer.json extension key
   • Git repository is properly referenced in TER
   • Documentation structure is valid
3. Approval: Once approved, future builds are automatic
4. Notification: Check Intercept dashboard for approval status

Typical Approval Time: 1-3 business days

Verification

Check Webhook Delivery

GitHub:

1. Go to Settings → Webhooks
2. Click on the webhook
3. Scroll to Recent Deliveries
4. Verify delivery shows 200 response code

GitLab:

1. Go to Settings → Webhooks
2. Click Edit on the webhook
3. Scroll to Recent events
4. Verify event shows success status

Check Intercept Dashboard

1. Visit: https://intercept.typo3.com/
2. Check Recent Actions: View recent webhook triggers
3. Documentation Deployments: https://intercept.typo3.com/admin/docs/deployments
4. Search for Your Extension: Filter by package name

Verify Published Documentation

Once approved and rendered successfully:

Published URL Pattern:

https://docs.typo3.org/p/{vendor}/{extension}/{branch}/en-us/

Example:

https://docs.typo3.org/p/netresearch/rte-ckeditor-image/main/en-us/

Version-Specific URLs:

https://docs.typo3.org/p/{vendor}/{extension}/{version}/en-us/

Triggering Documentation Builds

Automatic Triggers

Documentation builds are triggered automatically by:

1. Git Push to Main/Master

   git push origin main
   

2. Version Tags

   git tag 2.1.0
   git push origin 2.1.0
   

3. Branch Push (for multi-version documentation)

   git push origin docs-v12
   

Manual Trigger

If automatic builds fail or you need to rebuild:

1. Visit: https://intercept.typo3.com/admin/docs/deployments
2. Find your extension
3. Click Redeploy button
4. Monitor build progress in Recent actions

Build Process

Understanding the rendering pipeline:

1. Webhook Received: Intercept receives push notification
2. Queue Job: Build job added to rendering queue
3. Clone Repository: Code checked out at specific commit/tag
4. Render Documentation: Using ghcr.io/typo3-documentation/render-guides:latest
5. Publish: Rendered HTML published to docs.typo3.org
6. Index: Documentation indexed for search

Typical Build Time: 2-5 minutes

Troubleshooting

Webhook Not Triggering

Check:

• Webhook URL is exactly https://docs-hook.typo3.org
• SSL verification is enabled
• Webhook is marked as "Active"
• Recent deliveries show 200 response

Fix:

1. Edit webhook settings
2. Verify URL and SSL settings
3. Click Redeliver on failed delivery
4. Check Intercept Recent actions

Build Failing

Common Issues:

1. RST Syntax Errors

   # Validate locally before pushing
   ~/.claude/skills/typo3-docs/scripts/validate_docs.sh
   

2. Missing Settings.cfg

   # Check file exists
   ls -la Documentation/Settings.cfg
   

3. Invalid Cross-References

   • Render locally to check for broken :ref: links
   • Fix undefined labels

4. Encoding Issues

   • Ensure all files are UTF-8 encoded
   • Check for BOM (Byte Order Mark) issues

First Build Stuck "On Hold"

Expected Behavior: First build requires manual approval

Action:

• Wait for Documentation Team review (1-3 business days)
• Ensure TER registration is complete
• Verify Git repository URL in TER matches webhook source

Speed Up Approval:

• Post in TYPO3 Slack #typo3-documentation
• Reference your extension key and repository URL

Documentation Not Updating

Check:

1. Build Status: Visit Intercept dashboard, verify build succeeded
2. Cache: Browser cache might show old version
   • Hard refresh: Ctrl+F5 / Cmd+Shift+R
   • Try incognito/private mode
3. Correct URL: Verify you're visiting the right branch/version URL

Fix:

1. Trigger manual rebuild from Intercept dashboard
2. Check build logs for errors
3. Verify Settings.cfg has correct project configuration

Best Practices

Pre-Push Checklist

Before pushing documentation changes:

✅ Validate RST Syntax

~/.claude/skills/typo3-docs/scripts/validate_docs.sh /path/to/project

✅ Render Locally

~/.claude/skills/typo3-docs/scripts/render_docs.sh /path/to/project
open Documentation-GENERATED-temp/Index.html

✅ Check for Warnings

• No rendering warnings
• No broken cross-references
• All code blocks have language specified
• UTF-8 emoji icons render correctly

✅ Commit Message

git commit -m "docs: update configuration guide with new settings"

Version Management

Branching Strategy:

• main / master: Latest development documentation
• Version tags: Specific release documentation (e.g., 2.1.0, 3.0.0)
• Version branches: Long-term support versions (e.g., docs-v12, docs-v11)

Tag Documentation Builds:

# Create release tag
git tag -a 2.1.0 -m "Release 2.1.0"
git push origin 2.1.0

# Documentation auto-builds for version 2.1.0
# Published at: /p/{vendor}/{ext}/2.1.0/en-us/

Multi-Version Documentation

For supporting multiple TYPO3 versions:

1. Create Version Branches

   git checkout -b docs-v12
   git push origin docs-v12
   

2. Configure Settings.cfg for each branch

   [general]
   project = Extension Name
   release = 2.1.0
   version = 2.1
   

3. Webhook Triggers All Branches

   • Pushes to any branch trigger builds
   • Each branch published separately

Security Considerations

Webhook Secret (Optional)

While TYPO3 Intercept doesn't require webhook secrets, you can add them for extra security:

GitHub:

1. Generate random secret: openssl rand -hex 20
2. Add to webhook Secret field
3. Intercept validates using X-Hub-Signature header

GitLab:

1. Generate random secret
2. Add to webhook Secret token field
3. Intercept validates using X-Gitlab-Token header

Access Control

Documentation Repositories Should:

• Be publicly readable (required for Intercept access)
• Limit push access to trusted contributors
• Use branch protection for main/master
• Require pull request reviews for documentation changes

Avoid in Documentation:

• API keys, passwords, secrets
• Internal URLs, server hostnames
• Sensitive configuration details
• Personal information

Resources

Official Documentation:

• How to Document - Webhook Setup
• TYPO3 Intercept Dashboard
• Documentation Deployments

Community Support:

• TYPO3 Slack: #typo3-documentation
• TYPO3 Slack: #typo3-cms

Related Guides:

• TYPO3 Documentation Standards
• RST Syntax Reference
• TYPO3 Directives Reference