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

> Discover the purpose of the .github folder in Open-SEO. Learn how it automates CI, PR previews, Docker builds, and CODEOWNERS for efficient repository management.

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

---

**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`](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 enforces code quality and build verification on every change to `main` or any pull request. Located at [`.github/workflows/ci.yml`](https://github.com/every-app/open-seo/blob/main/.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

```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

```

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`](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 at [`.github/workflows/pr-preview.yml`](https://github.com/every-app/open-seo/blob/main/.github/workflows/pr-preview.yml) deploys temporary staging environments for pull requests. This enables reviewers to interact with live changes 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

```

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

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

```text
/.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`](https://github.com/every-app/open-seo/blob/main/AGENTS.md), [`CLAUDE.md`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/.github/workflows/ci.yml) | Primary continuous integration pipeline |
| [`.github/workflows/pr-preview.yml`](https://github.com/every-app/open-seo/blob/main/.github/workflows/pr-preview.yml) | Ephemeral preview environment deployment |
| [`.github/workflows/docker-image.yml`](https://github.com/every-app/open-seo/blob/main/.github/workflows/docker-image.yml) | Self-hosted Docker image generation |
| [`.github/workflows/sourcemaps.yml`](https://github.com/every-app/open-seo/blob/main/.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`](https://github.com/every-app/open-seo/blob/main/ci.yml)** runs quality checks on every PR and push to `main` using pnpm, Node.js 22, and Vite
- **[`pr-preview.yml`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/.github/workflows/sourcemaps.yml) file handles source map artifact generation and publishing, enabling production error debugging with original source references.