What Is the Purpose of the `.github` Directory in Open‑SEO?

The .github directory in every-app/open-seo contains GitHub Actions workflows, CODEOWNERS rules, and CI configuration that automate testing, building, and deploying the SEO toolkit while enforcing repository governance.

The .github folder follows GitHub's convention for storing repository‑wide metadata and automation scripts. In open‑seo, this directory is the control center for continuous integration, pull‑request previews, and code review policies. It ensures every code change passes quality gates before reaching production.

GitHub Actions Workflows in .github/workflows/

The .github/workflows/ subdirectory holds YAML files that define automated pipelines. These run on every push to main and every pull request, removing manual steps from the development cycle.

Main CI Pipeline (ci.yml)

The ci.yml workflow is the primary quality gate. It installs dependencies with pnpm, runs linting and tests, builds the worker bundle, and compiles the web front‑end.

name: CI
on:
  pull_request:
  push:
    branches: [main]

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup pnpm
        uses: pnpm/action-setup@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      - name: Run CI checks
        run: pnpm run ci:check
      - name: Run tests
        run: pnpm run test:ci
      - name: Build worker (eager‑bundle guard)
        run: pnpm vite build

Key functions of this workflow:

• Dependency integrity: Uses --frozen-lockfile to guarantee reproducible installs.
• Node.js 22: Pins the runtime version to prevent environment drift.
• Eager‑bundle guard: Builds the worker bundle to catch bundling errors early.
• Docker job: Triggers a parallel build for the self‑hosted Docker image.

PR Preview Deployment (pr-preview.yml)

The pr-preview.yml workflow creates temporary preview environments for each open pull request. This lets reviewers test changes in a live Cloudflare Workers environment before merging.

name: PR Preview
on:
  pull_request:
    types: [opened, synchronize, reopened, closed]
    paths-ignore:
      - "**/*.md"
      - docs/**
      - web/**
      - badseo/**

jobs:
  preview:
    if: github.repository == 'bensenescu/open-seo' &&
        github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup pnpm
        uses: pnpm/action-setup@v4
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      - name: Deploy preview stage
        if: github.event.action != 'closed'
        run: pnpm deploy:preview --stage "$STAGE" --yes

Security and safety measures in this workflow:

• Sandboxed execution: Only runs for PRs from the original repository, preventing secret exfiltration from forks.
• Path filtering: Ignores documentation and website changes that don't affect the core worker.
• Cloudflare Access verification: Confirms the preview URL is protected before posting the link.

Docker Image Build (docker-image.yml)

Located at .github/workflows/docker-image.yml, this workflow builds and publishes the self‑hosted Docker container. It enables users to run open‑seo on their own infrastructure without relying on Cloudflare's hosted version.

Source Map Upload (sourcemaps.yml)

The sourcemaps.yml workflow handles uploading source‑map artifacts for error tracking. This makes production debugging possible despite the bundled and minified output.

CODEOWNERS Governance

The .github/CODEOWNERS file enforces mandatory review rules for critical paths. It requires explicit approval from the repository maintainer for changes that could compromise CI integrity.

/.github/ @bensenescu
/.greptile/ @bensenescu
/AGENTS.md @bensenescu
/CLAUDE.md @bensenescu
/.agents/skills/ @bensenescu

This pattern protects:

• Workflow files: Prevents unauthorized modifications to CI/CD pipelines.
• Agent configuration: Safeguards AI‑agent instructions and tool definitions.
• Core documentation: Ensures consistency in project‑level guidance documents.

Why the .github Directory Structure Matters

The organization of .github in open‑seo follows best practices for open‑source maintainability:

• Reproducibility: All environment setup is codified; no "works on my machine" issues.
• Security: CODEOWNERS blocks supply‑chain attacks via workflow tampering.
• Contributor experience: Automated checks give immediate feedback without waiting for human review.
• Deployment confidence: Every merge to main has passed identical tests in a clean environment.

Summary

• The .github directory stores GitHub Actions workflows, CODEOWNERS rules, and repository metadata for open‑seo.
• .github/workflows/ci.yml runs lint, test, and build checks on every PR and push to main.
• .github/workflows/pr-preview.yml deploys temporary Cloudflare Workers environments for safe manual testing.
• .github/workflows/docker-image.yml produces self‑hosted Docker images.
• .github/CODEOWNERS requires maintainer approval for changes to CI configuration and agent files.

Frequently Asked Questions

What happens if I modify a file in .github/workflows/ without maintainer approval?

The CODEOWNERS rule /.github/ @bensenescu blocks merge until @bensenescu explicitly reviews the change. This prevents contributors from injecting malicious steps into CI pipelines or exfiltrating secrets.

Does the PR preview work for forks of open‑seo?

No. The condition github.event.pull_request.head.repo.full_name == github.repository prevents the preview workflow from running on fork‑based PRs. This security measure ensures Cloudflare API tokens are never exposed to untrusted code.

How does pnpm install --frozen-lockfile improve CI reliability?

This flag fails the build if pnpm-lock.yaml is out of sync with package.json. It guarantees that every CI run uses identical dependency versions, eliminating "flaky" builds caused by transitive package updates.

Where is the Docker image published?

The docker-image.yml workflow builds the image and typically publishes it to GitHub Container Registry (ghcr.io) or Docker Hub. Check the workflow file's push step for the exact registry and tagging scheme used in open‑seo.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}