Skip to main content

Documentation CI/CD Pipeline

This page details the automated build and deployment pipeline used to maintain and serve the Ressa Documentation site. The infrastructure follows a "Documentation as Code" philosophy, leveraging Git-based triggers and automated CI/CD workflows.

Architecture Overview​

The deployment pipeline consists of four primary stages:

  1. Source: Development on a private Forgejo instance.
  2. CI/CD: Automated build via Forgejo Actions.
  3. Artifact Synchronization: Mirroring to GitHub.
  4. Edge Hosting: Delivery via Cloudflare Pages.

Pipeline Details​

1. Source Control (Forgejo)​

The primary source of truth is hosted at: Ressa Docusaurus Source.

  • Trigger: Any push to the main branch initiates the deployment sequence.
  • Workflow: The build-docusaurus action manages the build environment using Node.js 20.
  • Artifact Generation: The workflow executes npm run build, generating optimized static assets. These assets are then pushed to a dedicated, orphan branch named docusaurus-html.

2. Repository Mirroring (GitHub)​

To integrate with external hosting providers, the Forgejo instance is configured to automatically mirror the docusaurus-html branch to GitHub.

  • Mirror Destination: GitHub Repository.
  • Purpose: This repository acts as a public-facing buffer and deployment trigger for edge hosting.

3. Production Hosting (Cloudflare Pages)​

The final production website is served via Cloudflare Pages.

  • Integration: Cloudflare is connected directly to the GitHub mirror.
  • Deployment: Cloudflare monitors the docusaurus-html branch. Upon detecting a change (pushed by the Forgejo mirror), it automatically pulls the new static files and distributes them across its global edge network.
  • Configuration: All routing and SSL termination are handled via the Cloudflare dashboard, ensuring low latency and high availability.

Security and Maintenance​

  • Secrets Management: The workflow utilizes Forgejo Integrated CI/CD Secrets (GITEA_TOKEN), eliminating the need for hardcoded credentials.
  • Automation: No manual intervention is required between committing a change and the update appearing live on the production URL.

Conclusion​

By decoupling the development environment from the production delivery network, this architecture provides a resilient and scalable way to manage system documentation.