Purpose of the `.github` Folder in Open-SEO: Complete Guide to GitHub Repository Automation

The .github folder in the Open-SEO repository stores GitHub Actions workflows for continuous integration, automated PR previews, Docker builds, and CODEOWNERS governance rules that enforce maintainer review requirements.

The .github directory is GitHub's standard location for repository-level automation and metadata. In the open-seo project (every-app/open-seo), this folder contains YAML workflow definitions, ownership rules, and configuration files that power the entire development pipeline—from code submission to production deployment.

---

What's Inside the .github Folder in Open-SEO

The Open-SEO .github folder organizes three categories of automation assets:

Category	Location	Purpose
CI/CD Workflows	.github/workflows/	Automated testing, building, and deployment
Ownership Rules	.github/CODEOWNERS	Mandatory reviewer assignments for sensitive paths
Supplementary Configs	Various workflow files	Source maps, Docker images, preview environments

---

GitHub Actions Workflows

Workflow files in .github/workflows/ define event-driven automation that executes on every push, pull request, or scheduled trigger.

Main CI Pipeline: ci.yml

The ci.yml workflow enforces code quality and build verification on every change to main or any pull request. Located at .github/workflows/ci.yml, it performs:

1. Dependency installation via pnpm with frozen lockfile
2. Linting and type checking via pnpm run ci:check
3. Unit test execution via pnpm run test:ci
4. Worker bundle compilation via Vite
5. Website build for the web frontend
6. Docker image build for self-hosted deployments

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

This workflow uses Node.js 22 and caches pnpm dependencies for speed. The ci:check script combines linting, formatting checks, and TypeScript compilation in a single command.

Pull Request Previews: pr-preview.yml

The pr-preview.yml workflow at .github/workflows/pr-preview.yml deploys temporary staging environments for pull requests. This enables reviewers to interact with live changes 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

Key implementation details:

• Security restriction: Only runs for PRs from the original repository (every-app/open-seo at bensenescu/open-seo), preventing secret exfiltration via forks
• Path filtering: Ignores documentation and asset-only changes
• Cloudflare Workers deployment: Uses CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID secrets with a .env.preview configuration
• Access verification: Confirms Cloudflare Access protection before posting preview URLs

Docker Image Builds: docker-image.yml

Additional workflows like .github/workflows/docker-image.yml and .github/workflows/sourcemaps.yml handle specialized build artifacts. The Docker workflow produces self-hostable container images, while sourcemaps uploads enable production debugging.

---

CODEOWNERS: Enforced Review Requirements

The .github/CODEOWNERS file mandates specific reviewers for critical repository paths. In Open-SEO, this ensures infrastructure changes receive maintainer scrutiny.

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

This configuration requires @bensenescu to approve any modifications to:

• CI/CD pipelines (.github/ folder)
• AI agent configurations (.greptile/, AGENTS.md, CLAUDE.md)
• Agent skill definitions (.agents/skills/)

CODEOWNERS integrates directly with GitHub's branch protection rules, blocking merges until designated owners submit approving reviews.

---

Workflow Design Patterns in Open-SEO

The Open-SEO .github folder demonstrates several production-quality automation patterns:

Consistent tooling chain — All workflows use pnpm as the package manager with action-setup@v4 for reproducible installs.

Matrix-friendly structure — The CI job layout supports future expansion to multiple Node.js versions or operating systems.

Secret security — Preview deployments validate repository ownership before accessing Cloudflare credentials, preventing supply-chain attacks via forked PRs.

Conditional execution — Jobs use if: expressions and paths-ignore to skip unnecessary work, conserving GitHub Actions minutes.

---

File Reference: Complete .github Contents

Path	Function
.github/workflows/ci.yml	Primary continuous integration pipeline
.github/workflows/pr-preview.yml	Ephemeral preview environment deployment
.github/workflows/docker-image.yml	Self-hosted Docker image generation
.github/workflows/sourcemaps.yml	Source map artifact publishing
.github/CODEOWNERS	Mandatory reviewer assignments

---

Summary

• .github/workflows/ contains YAML definitions for automated CI/CD pipelines that test, build, and deploy the Open-SEO project
• ci.yml runs quality checks on every PR and push to main using pnpm, Node.js 22, and Vite
• pr-preview.yml deploys temporary Cloudflare Workers environments for PR review, with security restrictions against fork-based attacks
• .github/CODEOWNERS enforces @bensenescu review requirements for all CI/CD and agent configuration changes
• Together these files eliminate manual deployment steps, ensure reproducible builds, and maintain security governance for the open-seo codebase

---

Frequently Asked Questions

What happens if I modify files in the .github folder?

GitHub will automatically require @bensenescu to approve your pull request before merging, as specified in the CODEOWNERS file. This protects CI/CD pipelines from unauthorized modifications.

Can forked pull requests trigger the preview deployment?

No. The pr-preview.yml workflow contains an explicit condition (github.event.pull_request.head.repo.full_name == github.repository) that prevents fork-based PRs from accessing Cloudflare deployment secrets, mitigating credential theft risks.

What Node.js version does Open-SEO use in CI?

All workflows specify Node.js 22 via actions/setup-node@v4 with node-version: 22, ensuring consistent runtime behavior across development and production environments.

Where are the source maps uploaded in Open-SEO's automation?

The .github/workflows/sourcemaps.yml file handles source map artifact generation and publishing, enabling production error debugging with original source references.

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