Build and Deploy Workflow

Loading…

Build and Deploy Workflow

Relevant source files

• .github/workflows/build-and-deploy.yml

Purpose and Scope

This page documents the Build and Deploy Workflow (.github/workflows/build-and-deploy.yml), which automates the process of building documentation from DeepWiki content and deploying it to GitHub Pages. The workflow runs on a weekly schedule and supports manual triggers with configurable parameters.

For information about testing the system’s Python components, see Test Workflow. For using this system in other repositories via the reusable action, see GitHub Action.

Workflow Overview

The Build and Deploy Workflow consists of two sequential jobs: build and deploy. The build job constructs the Docker image, generates the documentation artifacts, and uploads them. The deploy job then publishes these artifacts to GitHub Pages.

Sources: .github/workflows/build-and-deploy.yml:1-90

graph TB
    subgraph "Trigger Mechanisms"
        schedule["schedule\ncron: '0 0 * * 0'\n(Weekly Sunday 00:00 UTC)"]
manual["workflow_dispatch\n(Manual trigger)"]
end
    
    subgraph "Build Job"
        checkout["actions/checkout@v4\nClone repository"]
resolve["Resolve repository and book title\nCustom shell script"]
buildx["docker/setup-buildx-action@v3\nSetup Docker Buildx"]
dockerbuild["docker build -t deepwiki-to-mdbook ."]
dockerrun["docker run\nGenerate documentation"]
upload["actions/upload-pages-artifact@v3\nUpload ./output/book"]
end
    
    subgraph "Deploy Job"
        deploy["actions/deploy-pages@v4\nPublish to GitHub Pages"]
end
    
 
   schedule --> checkout
 
   manual --> checkout
 
   checkout --> resolve
 
   resolve --> buildx
 
   buildx --> dockerbuild
 
   dockerbuild --> dockerrun
 
   dockerrun --> upload
 
   upload --> deploy
    
 
   deploy --> pages["GitHub Pages\ngithub.io site"]

Trigger Configuration

Schedule-Based Execution

The workflow executes automatically on a weekly basis using a cron schedule:

This runs every Sunday at midnight UTC, ensuring the documentation stays synchronized with the latest DeepWiki content.

Manual Dispatch

The workflow_dispatch trigger allows on-demand execution through the GitHub Actions UI. Unlike the scheduled run, manual triggers can accept custom inputs for repository and book title configuration.

Sources: .github/workflows/build-and-deploy.yml:3-9

Permissions and Concurrency

GitHub Token Permissions

The workflow requires specific permissions for GitHub Pages deployment:

Concurrency Control

The concurrency configuration ensures only one deployment runs at a time using the pages group. Setting cancel-in-progress: false means new deployments wait for running deployments to complete rather than canceling them.

Sources: .github/workflows/build-and-deploy.yml:11-20

Build Job Architecture

Sources: .github/workflows/build-and-deploy.yml:23-78

Step 1: Repository Checkout

The workflow begins by checking out the repository using actions/checkout@v4:

This provides access to the Dockerfile and all scripts needed for the build process.

Sources: .github/workflows/build-and-deploy.yml:27-28

Step 2: Repository and Title Resolution

The resolution step implements fallback logic for configuring the documentation build:

Repository Resolution:

1. Check if github.event.inputs.repo was provided (manual trigger)
2. If not provided, use github.repository (current repository)
3. Store result in repo_value output

Title Resolution:

1. Check if github.event.inputs.book_title was provided
2. If not provided, extract repository name and append “ Documentation“
3. If extraction fails, use “Documentation” as fallback
4. Store result in title_value output

The resolved values are written to GITHUB_OUTPUT for use in subsequent steps:

Sources: .github/workflows/build-and-deploy.yml:30-58

Step 3: Docker Buildx Setup

The workflow uses Docker Buildx for enhanced build capabilities:

This provides BuildKit features, including improved caching and multi-platform builds (though this workflow builds for a single platform).

Sources: .github/workflows/build-and-deploy.yml:60-61

Step 4: Docker Image Build

The Docker image is built using the Dockerfile in the repository root:

This creates the deepwiki-to-mdbook image containing:

• mdBook and mdbook-mermaid binaries
• Python 3.12 runtime
• deepwiki-scraper.py and process-template.py scripts
• build-docs.sh orchestrator
• Default templates

For details on the Docker image structure, see Docker Multi-Stage Build.

Sources: .github/workflows/build-and-deploy.yml:63-64

Step 5: Documentation Builder Execution

The Docker container is executed with environment variables and a volume mount:

Container Configuration:

The container runs build-docs.sh (default CMD), which orchestrates the three-phase pipeline:

1. Phase 1: Extract markdown from DeepWiki (see Markdown Extraction)
2. Phase 2: Enhance with diagrams (see Diagram Enhancement)
3. Phase 3: Build mdBook artifacts (see mdBook Build)

Output is written to $(pwd)/output, which maps to /output inside the container.

Sources: .github/workflows/build-and-deploy.yml:66-72

Step 6: GitHub Pages Artifact Upload

The generated book directory is uploaded as a GitHub Pages artifact:

The actions/upload-pages-artifact action packages ./output/book into a tarball optimized for Pages deployment. This artifact is then available to the deploy job.

Sources: .github/workflows/build-and-deploy.yml:74-77

Deploy Job Architecture

Sources: .github/workflows/build-and-deploy.yml:79-90

Job Dependencies and Environment

The deploy job has a strict dependency on the build job:

This ensures the deploy job only runs after the build job successfully completes.

The environment configuration:

• name: github-pages - Associates deployment with the GitHub Pages environment
• url - Sets the environment URL to the deployed site URL from the deployment step

Deployment Step

The deployment uses the official GitHub Pages deployment action:

The deploy-pages action:

1. Downloads the artifact uploaded by the build job
2. Unpacks the tarball
3. Publishes content to GitHub Pages
4. Returns the deployed site URL in page_url output

Sources: .github/workflows/build-and-deploy.yml:79-89

Workflow Execution Flow

Sources: .github/workflows/build-and-deploy.yml:1-90

Environment Variables and Outputs

Step Outputs

The resolve step produces two outputs accessible to subsequent steps:

These outputs are consumed by the Docker run command via environment variables.

Docker Container Environment

The container receives configuration through environment variables:

Additional environment variables supported by the container (not set by this workflow) include:

• BOOK_AUTHORS - Author metadata
• BOOK_LANGUAGE - Language code (default: en)
• BOOK_SRC - Source directory (default: src)
• MARKDOWN_ONLY - Skip HTML build if set

For a complete list, see Configuration Reference.

Sources: .github/workflows/build-and-deploy.yml:30-72

Workflow Status and Monitoring

Build Job Success Criteria

The build job succeeds when:

1. Repository checkout completes
2. Resolution logic produces valid outputs
3. Docker image builds without errors
4. Container execution exits with code 0
5. Artifact upload completes

If any step fails, the build job terminates and the deploy job does not run.

Deploy Job Success Criteria

The deploy job succeeds when:

1. Build job completed successfully
2. Artifact download succeeds
3. GitHub Pages deployment completes
4. Deployment URL is accessible

Monitoring and Debugging

Workflow Execution:

• View workflow runs in the Actions tab: https://github.com/{owner}/{repo}/actions
• Each run shows both job statuses and step-by-step logs

Common Failure Points:

Sources: .github/workflows/build-and-deploy.yml:1-90

Integration with Other Components

Relationship to Test Workflow

The Build and Deploy Workflow does not include test execution. Testing is handled by a separate workflow that runs on push and PR events. See Test Workflow for details.

Relationship to GitHub Action

This workflow uses the same Docker image and build process as the reusable GitHub Action. The key differences:

For using this system in other repositories, see GitHub Action.

Docker Image Reuse

The workflow builds the Docker image fresh on each run. This ensures:

• Latest code changes are included
• Dependencies are up to date
• Reproducible builds from source

The image is not pushed to a registry; it exists only during workflow execution.

Sources: .github/workflows/build-and-deploy.yml:1-90

Deployment Target Configuration

GitHub Pages Environment

GitHub Pages deployment requires repository configuration:

1. Pages Source: Set to “GitHub Actions” in repository settings
2. Branch: Not applicable (artifact-based deployment)
3. Custom Domain: Optional; configure in repository settings

The deployment uses the github-pages environment, which provides:

• Protection rules (if configured)
• Deployment history
• Environment-specific secrets (if needed)

URL Structure

The deployed documentation is accessible at:

https://{owner}.github.io/{repo}/

For custom domains, the URL follows the custom domain configuration.

Sources: .github/workflows/build-and-deploy.yml:80-82

Workflow Customization

Modifying Schedule

To change the execution frequency, edit the cron expression:

Examples:

• Daily: "0 0 * * *"
• Twice weekly: Add another cron entry
• Monthly: "0 0 1 * *"

Adding Manual Inputs

While the current workflow supports manual trigger, it does not expose inputs in the workflow_dispatch section. To add configurable inputs, modify the trigger:

The resolution step already handles these inputs via github.event.inputs.*.

Sources: .github/workflows/build-and-deploy.yml:8-9

Performance Characteristics

Typical Execution Time

Resource Usage

The workflow runs on ubuntu-latest runners:

• CPU: 2 cores
• RAM: 7 GB
• Disk: 14 GB SSD

Docker build and Python scraping are the most resource-intensive operations.

Optimization Opportunities

1. Docker Layer Caching: The workflow could use actions/cache to cache Docker layers between runs
2. Build Artifact Reuse: Skip documentation rebuild if wiki content hasn’t changed
3. Parallel Jobs: Split build and test into parallel jobs (though this workflow has no tests)

Sources: .github/workflows/build-and-deploy.yml:1-90

Dismiss

Refresh this wiki

Enter email to refresh