← Watch feed
Add GitHub Pages documentation site with orchestrated workflows
Public commit record
100/100 · Strong
What the developer wrote
Authored by Christian Decker
Add GitHub Pages documentation site with orchestrated workflows
This commit creates a comprehensive documentation publishing system that
combines coverage reports, Python API docs, and project documentation into
a unified GitHub Pages site.
Changes:
- Update coverage-nightly.yaml to support workflow_call trigger
- Update python-docs-nightly.yaml to support workflow_call trigger
- Add docs-nightly.yaml workflow for project documentation
- Add publish-site.yaml orchestrator workflow
The publish-site workflow:
- Triggers all three documentation workflows in parallel
- Collects artifacts from each workflow
- Organizes them into a unified site structure:
- / (root) - Beautiful landing page with navigation
- /docs/ - Project documentation
- /python/ - Python API reference (pdoc3)
- /coverage/ - Code coverage reports
- Deploys to GitHub Pages with proper permissions
- Runs nightly at 5 AM UTC, after all other workflows complete
Each workflow can be:
- Triggered manually via workflow_dispatch
- Called from other workflows via workflow_call
- Run on schedule (coverage: 2 AM, python-docs: 3 AM, docs: 4 AM)
The site includes:
- Modern, responsive landing page with gradient design
- Navigation cards for each documentation section
- 404 error page
- .nojekyll file to prevent Jekyll processing
- Automatic timestamp updates
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Changelog-None
✓ Specific, descriptive subject✓ Names a concrete action or component✓ Provides detailed explanatory context✓ Explains rationale or failure mode✓ Mentions testing or verification✓ Links an issue, advisory, or supporting reference
What changed, and why it matters
This commit adds GitHub Actions workflows to automatically build and publish a documentation website to GitHub Pages. It only touches CI/CD configuration and static HTML pages; it does not change any Core Lightning node code, wallet logic, or network handling. There is no apparent security vulnerability in the diff itself.
Recommended action
No security action required. As a routine hardening suggestion, ensure the `github-pages` environment requires approval before deployment in repository settings, and verify that the called workflows do not inherit excessive permissions beyond what the orchestrator grants.
Security signals we found
01
No changes to application code, cryptography, networking, or wallet logic
02
Uses official GitHub Actions for Pages deployment with standard OIDC permissions
03
Workflow permissions are limited to Pages deployment needs
04
No secrets, credentials, or tokens are hardcoded in the diff
05
No user-controlled input is processed by the added workflows
Evidence from the diff
The commit introduces four GitHub workflow files. Three existing/added workflows (coverage-nightly, python-docs-nightly, docs-nightly) are extended with workflow_call: triggers so they can be invoked by a new orchestrator workflow publish-site.yaml. The orchestrator downloads artifacts, builds a landing page, a 404 page, and a .nojekyll file, then deploys to GitHub Pages using official GitHub actions (actions/configure-pages, actions/upload-pages-artifact, actions/deploy-pages). Permissions are scoped to contents: read, pages: write, id-token: write as required by GitHub Pages OIDC deployment. No source code of the lightning daemon is modified.
Changed components
.github/workflows/coverage-nightly.yaml.github/workflows/docs-nightly.yaml.github/workflows/publish-site.yaml.github/workflows/python-docs-nightly.yamlInspect captured patch +418 / −0
diff --git a/.github/workflows/coverage-nightly.yaml b/.github/workflows/coverage-nightly.yaml
index c025a1a3..dfa89686 100644
--- a/.github/workflows/coverage-nightly.yaml
+++ b/.github/workflows/coverage-nightly.yaml
@@ -6,6 +6,8 @@ on:
- cron: '0 2 * * *'
# Allow manual triggers for testing
workflow_dispatch:
+ # Allow being called from other workflows
+ workflow_call:
concurrency:
group: coverage-${{ github.ref }}
diff --git a/.github/workflows/docs-nightly.yaml b/.github/workflows/docs-nightly.yaml
new file mode 100644
index 00000000..ed2f3d75
--- /dev/null
+++ b/.github/workflows/docs-nightly.yaml
@@ -0,0 +1,100 @@
+name: Documentation (Nightly)
+
+on:
+ schedule:
+ # Run at 4 AM UTC every day
+ - cron: '0 4 * * *'
+ # Allow manual triggers for testing
+ workflow_dispatch:
+ # Allow being called from other workflows
+ workflow_call:
+
+concurrency:
+ group: docs-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ generate-docs:
+ name: Generate Project Documentation
+ runs-on: ubuntu-22.04
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Prepare documentation directory
+ run: |
+ mkdir -p docs-output
+ cp -r doc/* docs-output/
+
+ # Create a simple index.html for the documentation
+ cat > docs-output/index.html <<'EOF'
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Core Lightning Documentation</title>
+ <style>
+ body {
+ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+ max-width: 1200px;
+ margin: 0 auto;
+ padding: 40px 20px;
+ line-height: 1.6;
+ }
+ h1 {
+ border-bottom: 2px solid #eaecef;
+ padding-bottom: 0.3em;
+ }
+ .docs-list {
+ list-style: none;
+ padding: 0;
+ }
+ .docs-list li {
+ padding: 8px 0;
+ }
+ .docs-list a {
+ color: #0366d6;
+ text-decoration: none;
+ font-family: monospace;
+ }
+ .docs-list a:hover {
+ text-decoration: underline;
+ }
+ .section {
+ margin-top: 30px;
+ }
+ </style>
+ </head>
+ <body>
+ <h1>Core Lightning Documentation</h1>
+ <p>Welcome to the Core Lightning documentation site.</p>
+
+ <div class="section">
+ <h2>Available Documentation</h2>
+ <p>This site contains the complete documentation for Core Lightning.</p>
+ <ul>
+ <li><a href="../">← Back to main site</a></li>
+ </ul>
+ </div>
+
+ <div class="section">
+ <p>For the full documentation, please visit the <a href="https://github.com/ElementsProject/lightning/tree/master/doc">doc directory on GitHub</a>.</p>
+ </div>
+ </body>
+ </html>
+ EOF
+
+ - name: Upload documentation artifact
+ uses: actions/upload-artifact@v4
+ with:
+ name: project-docs
+ path: docs-output
+ retention-days: 90
+
+ - name: Add summary to job
+ run: |
+ echo "## Project Documentation Generated" >> $GITHUB_STEP_SUMMARY
+ echo "" >> $GITHUB_STEP_SUMMARY
+ echo "📖 Documentation files have been collected and prepared." >> $GITHUB_STEP_SUMMARY
+ echo "" >> $GITHUB_STEP_SUMMARY
+ echo "Download the artifact to view the documentation." >> $GITHUB_STEP_SUMMARY
diff --git a/.github/workflows/publish-site.yaml b/.github/workflows/publish-site.yaml
new file mode 100644
index 00000000..376bb6f5
--- /dev/null
+++ b/.github/workflows/publish-site.yaml
@@ -0,0 +1,314 @@
+name: Publish Documentation Site
+
+on:
+ schedule:
+ # Run at 5 AM UTC every day, after other workflows
+ - cron: '0 5 * * *'
+ # Allow manual triggers for testing
+ workflow_dispatch:
+
+# Sets permissions for GitHub Pages deployment
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+ group: pages
+ cancel-in-progress: false
+
+jobs:
+ # Generate coverage reports
+ coverage:
+ name: Generate Coverage Reports
+ uses: ./.github/workflows/coverage-nightly.yaml
+
+ # Generate Python API documentation
+ python-docs:
+ name: Generate Python API Documentation
+ uses: ./.github/workflows/python-docs-nightly.yaml
+
+ # Generate general documentation
+ docs:
+ name: Generate Project Documentation
+ uses: ./.github/workflows/docs-nightly.yaml
+
+ # Combine all documentation and deploy to GitHub Pages
+ deploy:
+ name: Deploy to GitHub Pages
+ runs-on: ubuntu-22.04
+ needs: [coverage, python-docs, docs]
+ if: always() # Run even if some jobs fail
+
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Download coverage artifact
+ uses: actions/download-artifact@v4
+ continue-on-error: true
+ with:
+ name: coverage-html-report
+ path: site-staging/coverage
+
+ - name: Download Python docs artifact
+ uses: actions/download-artifact@v4
+ continue-on-error: true
+ with:
+ name: python-api-docs
+ path: site-staging/python
+
+ - name: Download project docs artifact
+ uses: actions/download-artifact@v4
+ continue-on-error: true
+ with:
+ name: project-docs
+ path: site-staging/docs
+
+ - name: Create site index
+ run: |
+ cat > site-staging/index.html <<'EOF'
+ <!DOCTYPE html>
+ <html lang="en">
+ <head>
+ <meta charset="UTF-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <title>Core Lightning Documentation Hub</title>
+ <style>
+ * {
+ margin: 0;
+ padding: 0;
+ box-sizing: border-box;
+ }
+
+ body {
+ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+ line-height: 1.6;
+ color: #24292e;
+ background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+ min-height: 100vh;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ padding: 20px;
+ }
+
+ .container {
+ max-width: 1000px;
+ width: 100%;
+ background: white;
+ border-radius: 12px;
+ box-shadow: 0 20px 60px rgba(0,0,0,0.3);
+ overflow: hidden;
+ }
+
+ .header {
+ background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+ color: white;
+ padding: 60px 40px;
+ text-align: center;
+ }
+
+ .header h1 {
+ font-size: 2.5em;
+ margin-bottom: 10px;
+ font-weight: 600;
+ }
+
+ .header p {
+ font-size: 1.2em;
+ opacity: 0.9;
+ }
+
+ .content {
+ padding: 40px;
+ }
+
+ .intro {
+ text-align: center;
+ margin-bottom: 40px;
+ color: #586069;
+ }
+
+ .cards {
+ display: grid;
+ grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+ gap: 24px;
+ margin-top: 30px;
+ }
+
+ .card {
+ background: #f6f8fa;
+ border: 2px solid #e1e4e8;
+ border-radius: 8px;
+ padding: 30px;
+ transition: all 0.3s ease;
+ text-decoration: none;
+ color: inherit;
+ display: block;
+ }
+
+ .card:hover {
+ transform: translateY(-4px);
+ box-shadow: 0 8px 24px rgba(0,0,0,0.15);
+ border-color: #667eea;
+ }
+
+ .card-icon {
+ font-size: 2.5em;
+ margin-bottom: 15px;
+ }
+
+ .card h2 {
+ font-size: 1.4em;
+ margin-bottom: 12px;
+ color: #24292e;
+ }
+
+ .card p {
+ color: #586069;
+ font-size: 0.95em;
+ line-height: 1.5;
+ }
+
+ .footer {
+ text-align: center;
+ padding: 30px;
+ color: #586069;
+ font-size: 0.9em;
+ border-top: 1px solid #e1e4e8;
+ }
+
+ .footer a {
+ color: #667eea;
+ text-decoration: none;
+ }
+
+ .footer a:hover {
+ text-decoration: underline;
+ }
+
+ .timestamp {
+ margin-top: 15px;
+ font-size: 0.85em;
+ opacity: 0.7;
+ }
+ </style>
+ </head>
+ <body>
+ <div class="container">
+ <div class="header">
+ <h1>⚡ Core Lightning</h1>
+ <p>Documentation Hub</p>
+ </div>
+
+ <div class="content">
+ <div class="intro">
+ <p>Welcome to the Core Lightning documentation portal. Choose a category below to explore.</p>
+ </div>
+
+ <div class="cards">
+ <a href="docs/" class="card">
+ <div class="card-icon">📖</div>
+ <h2>Documentation</h2>
+ <p>Project documentation, guides, and reference materials for Core Lightning.</p>
+ </a>
+
+ <a href="python/" class="card">
+ <div class="card-icon">🐍</div>
+ <h2>Python API Reference</h2>
+ <p>Complete API documentation for pyln.client, pyln.proto, and other Python packages.</p>
+ </a>
+
+ <a href="coverage/" class="card">
+ <div class="card-icon">📊</div>
+ <h2>Code Coverage</h2>
+ <p>Test coverage reports showing which parts of the codebase are tested.</p>
+ </a>
+ </div>
+ </div>
+
+ <div class="footer">
+ <p>
+ <a href="https://github.com/ElementsProject/lightning">View on GitHub</a> •
+ <a href="https://github.com/ElementsProject/lightning/issues">Report Issue</a>
+ </p>
+ <p class="timestamp">Last updated: TIMESTAMP</p>
+ </div>
+ </div>
+ </body>
+ </html>
+ EOF
+
+ # Update timestamp
+ TIMESTAMP=$(date -u +"%Y-%m-%d %H:%M UTC")
+ sed -i "s/TIMESTAMP/$TIMESTAMP/" site-staging/index.html
+
+ - name: Add .nojekyll to prevent Jekyll processing
+ run: |
+ touch site-staging/.nojekyll
+
+ - name: Create 404 page
+ run: |
+ cat > site-staging/404.html <<'EOF'
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>404 - Page Not Found</title>
+ <style>
+ body {
+ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ min-height: 100vh;
+ margin: 0;
+ background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+ color: white;
+ text-align: center;
+ }
+ .container { max-width: 600px; padding: 40px; }
+ h1 { font-size: 6em; margin: 0; }
+ p { font-size: 1.2em; margin: 20px 0; }
+ a { color: white; text-decoration: underline; }
+ </style>
+ </head>
+ <body>
+ <div class="container">
+ <h1>404</h1>
+ <p>Page not found</p>
+ <p><a href="/">← Return to documentation hub</a></p>
+ </div>
+ </body>
+ </html>
+ EOF
+
+ - name: Setup Pages
+ uses: actions/configure-pages@v5
+
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: site-staging
+
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
+
+ - name: Add summary
+ run: |
+ echo "## 🚀 Documentation Site Deployed" >> $GITHUB_STEP_SUMMARY
+ echo "" >> $GITHUB_STEP_SUMMARY
+ echo "The complete documentation site has been deployed to GitHub Pages." >> $GITHUB_STEP_SUMMARY
+ echo "" >> $GITHUB_STEP_SUMMARY
+ echo "### Included Sections:" >> $GITHUB_STEP_SUMMARY
+ echo "- 📖 Project Documentation" >> $GITHUB_STEP_SUMMARY
+ echo "- 🐍 Python API Reference" >> $GITHUB_STEP_SUMMARY
+ echo "- 📊 Code Coverage Reports" >> $GITHUB_STEP_SUMMARY
+ echo "" >> $GITHUB_STEP_SUMMARY
+ echo "🔗 **Site URL:** ${{ steps.deployment.outputs.page_url }}" >> $GITHUB_STEP_SUMMARY
diff --git a/.github/workflows/python-docs-nightly.yaml b/.github/workflows/python-docs-nightly.yaml
index 8cff9ef5..aecff245 100644
--- a/.github/workflows/python-docs-nightly.yaml
+++ b/.github/workflows/python-docs-nightly.yaml
@@ -6,6 +6,8 @@ on:
- cron: '0 3 * * *'
# Allow manual triggers for testing
workflow_dispatch:
+ # Allow being called from other workflows
+ workflow_call:
concurrency:
group: python-docs-${{ github.ref }}
Risk score
Our methodology →Why this scored 15/100
Human-validated context
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
No validated notes yet.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.