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

> Discover the purpose of the .github directory in open-seo. Learn how it automates workflows, enforces governance, and streamlines CI processes for the SEO toolkit.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: internals
- Published: 2026-08-16

---

**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`](https://github.com/every-app/open-seo/blob/main/ci.yml))

The [`ci.yml`](https://github.com/every-app/open-seo/blob/main/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.

```yaml
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`](https://github.com/every-app/open-seo/blob/main/pr-preview.yml))

The [`pr-preview.yml`](https://github.com/every-app/open-seo/blob/main/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.

```yaml
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`](https://github.com/every-app/open-seo/blob/main/docker-image.yml))

Located at [`.github/workflows/docker-image.yml`](https://github.com/every-app/open-seo/blob/main/.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`](https://github.com/every-app/open-seo/blob/main/sourcemaps.yml))

The [`sourcemaps.yml`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/.github/workflows/ci.yml)** runs lint, test, and build checks on every PR and push to `main`.
- **[`.github/workflows/pr-preview.yml`](https://github.com/every-app/open-seo/blob/main/.github/workflows/pr-preview.yml)** deploys temporary Cloudflare Workers environments for safe manual testing.
- **[`.github/workflows/docker-image.yml`](https://github.com/every-app/open-seo/blob/main/.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`](https://github.com/every-app/open-seo/blob/main/pnpm-lock.yaml) is out of sync with [`package.json`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.