How to automate multilingual SEO validation with GitHub Actions before Cloudflare Pages deployment?

[sargutportfolio]

🏷️ Discussion Type

Question

Body

Hello GitHub Community,

I'm managing a multilingual portfolio website hosted on Cloudflare Pages, with its source code stored in a private GitHub repository.

The website supports Turkish, English, Arabic and Russian. We want to improve code quality and prevent deployment regressions.

I would appreciate practical programming guidance on implementing GitHub Actions checks for:

1. Validating reciprocal hreflang tags and self-referencing canonical URLs across language versions.
2. Checking robots.txt, sitemap.xml and internal links for broken URLs.
3. Validating JSON-LD syntax and schema.org structured data.
4. Detecting missing image dimensions, alt attributes and potential mobile performance issues.
5. Testing generated static pages and Cloudflare Pages preview deployments before merging into main.
6. Blocking deployment or merge when critical checks fail, without exposing repository secrets.

Which free, maintained open-source tools or GitHub Actions workflows would you recommend? A minimal example workflow or implementation approach would be especially helpful.

We would like to test everything in a private preview environment and avoid any changes to production until the results have been reviewed.

The repository is private, so please suggest approaches that do not require making its contents public.

This question was drafted with assistance from ChatGPT (OpenAI, GPT-5.6 Sol) and reviewed before posting.

Thank you.

Guidelines

• I have read and understood this category's guidelines before making this post.

[Dev4Bht]

A good approach is to run all SEO checks in GitHub Actions before allowing a merge to main.
You can use Lighthouse CI for SEO, accessibility and performance checks, a broken-link checker for internal URLs, and a small Node.js script to validate hreflang, canonical tags and JSON-LD.
The workflow could be:
Pull Request → Build static site → Start local preview → Check links/HTML/SEO → Run Lighthouse CI → Pass or Fail → Review → Merge → Cloudflare Pages deployment
For Cloudflare preview deployments, you can run the same tests against the preview URL before approving production.
For a private repository, keep API tokens and other credentials in GitHub Actions Secrets and never hardcode them in workflow files. Also configure branch protection so the PR cannot be merged when critical SEO or build checks fail.
This gives you a safe setup where problems are caught before they reach production while keeping the repository private.

[TheVingance]

Validating Multilingual SEO Before Deployment

Hi @sargutportfolio,

Validating multilingual SEO and static assets before reaching production is best handled with a two-tier pipeline:

1. Pre-deploy static checks (on pull requests): Build the static files inside the runner and inspect the generated HTML directly. This allows fast, zero-cost auditing of hreflang, canonical links, broken URLs, and JSON-LD schema without exposing preview URLs or API tokens.
2. Post-deploy preview checks: Run mobile performance audits (Lighthouse CI) against either the local build artifacts or the private Cloudflare Pages preview URL.

---

Recommended Open-Source Tooling

• hreflang, canonicals & broken links: lychee or a custom Cheerio script. Lychee is a fast, maintained link checker with native support for local HTML directory trees and XML sitemaps.
• JSON-LD & Schema.org: ajv or a custom Node.js parser. Validates schema structures locally inside the runner without relying on third-party API rate limits.
• Image dimensions & HTML validation: html-validate or htmlhint. Asserts required alt tags and explicit width/height attributes to prevent Cumulative Layout Shift (CLS).
• Performance & Mobile Audits: @lhci/cli. Google's official CLI to enforce minimum thresholds on SEO, performance, and accessibility.

---

1. Custom Pre-Deployment SEO Auditor

A dedicated Node.js script using cheerio and glob is the cleanest way to guarantee reciprocal hreflang coverage across your four locales (tr, en, ar, ru).

Create .github/scripts/seo-audit.mjs:

import fs from 'node:fs';
import path from 'node:path';
import * as cheerio from 'cheerio';
import { globSync } from 'glob';

const distDir = path.resolve('out'); // Adjust to your static output folder (e.g. dist, build, out)
const htmlFiles = globSync(`${distDir}/**/*.html`);
let hasError = false;

console.log(`Auditing SEO across ${htmlFiles.length} HTML files...`);

for (const file of htmlFiles) {
  const content = fs.readFileSync(file, 'utf-8');
  const $ = cheerio.load(content);

  // 1. Validate Canonical URL
  const canonical = $('link[rel="canonical"]').attr('href');
  if (!canonical) {
    console.error(`❌ [Missing Canonical] in ${file}`);
    hasError = true;
  }

  // 2. Validate Hreflang Tags (Reciprocal check)
  const hreflangs = {};
  $('link[rel="alternate"][hreflang]').each((_, el) => {
    hreflangs[$(el).attr('hreflang')] =$(el).attr('href');
  });

  const requiredLocales = ['tr', 'en', 'ar', 'ru', 'x-default'];
  for (const locale of requiredLocales) {
    if (!hreflangs[locale]) {
      console.warn(`⚠️ [Missing hreflang="${locale}"] in ${file}`);
    }
  }

  // 3. Validate Images (alt tags and explicit dimensions)
  $('img').each((_, el) => {
    const alt = $(el).attr('alt');
    const width = $(el).attr('width');
    const height = $(el).attr('height');
    const src = $(el).attr('src');

    if (alt === undefined) {
      console.error(`❌ [Missing alt attribute] on image ${src} in ${file}`);
      hasError = true;
    }
    if (!width || !height) {
      console.warn(`⚠ [Missing dimensions / CLS risk] on image ${src} in ${file}`);
    }
  });

  // 4. Validate JSON-LD Schema syntax
  $('script[type="application/ld+json"]').each((_, el) => {
    try {
      JSON.parse($(el).text());
    } catch (e) {
      console.error(`❌ [Malformed JSON-LD Syntax] in ${file}: ${e.message}`);
      hasError = true;
    }
  });
}

if (hasError) {
  process.exit(1);
} else {
  console.log('✅ All pre-deployment SEO audits passed.');
}

---

2. GitHub Actions Gatekeeper Workflow

This workflow triggers on pull requests targeting main. It builds the application, executes the SEO script, runs lychee against internal links, and blocks merging if regressions are detected.

Create .github/workflows/seo-gatekeeper.yml:

name: Multilingual SEO & Quality Gatekeeper

on:
  pull_request:
    branches: [main]

jobs:
  seo-and-performance-audit:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Install Dependencies
        run: npm ci

      - name: Build Static Site
        run: npm run build # Ensure this outputs to ./out or ./dist

      - name: Run Custom SEO & Hreflang Auditor
        run: node .github/scripts/seo-audit.mjs

      - name: Check Broken Internal Links & Sitemaps with Lychee
        uses: lycheeverse/lychee-action@v2
        with:
          args: --offline --include-fragments ./out/**/*.html
          fail: true

      - name: Audit Mobile Performance & SEO via Lighthouse CI
        run: |
          npm install -g @lhci/cli
          lhci autorun
        env:
          LHCI_BUILD_CONTEXT__CURRENT_HASH: ${{ github.sha }}

Create a .lighthouserc.json in your repository root to enforce assertion thresholds:

{
  "ci": {
    "collect": {
      "staticDistDir": "./out",
      "numberOfRuns": 1
    },
    "assert": {
      "assertions": {
        "categories:seo": ["error", { "minScore": 0.95 }],
        "categories:performance": ["warn", { "minScore": 0.85 }],
        "document-title": "error",
        "html-has-lang": "error",
        "valid-lang": "error"
      }
    }
  }
}

---

3. Enforcing Merges & Keeping Secrets Safe

• Zero-Secret CI: Because this workflow tests compiled static assets directly inside the runner, you do not need to share Cloudflare API credentials, access tokens, or sensitive deployment hooks with pull requests.
• Branch Protection: Navigate to Settings > Branches > Branch protection rules on your repository. For main, enable Require status checks to pass before merging and choose seo-and-performance-audit. Cloudflare Pages will only deploy commits that have successfully cleared the audit.

---

If this provides a solid foundation for your multilingual validation pipeline, please consider marking this reply as Answered so others in the community can find it easily.

[idrivehtbusiness]

I'd keep the validation separate from the Cloudflare deployment itself. The earlier suggestions cover the right tools, but there are two details I'd pay particular attention to.

First, checking that an hreflang tag exists isn't enough. You need to verify that the destination page exists and links back to the original page.

For example, if /en/about/ declares /tr/about/ as its Turkish version, the Turkish page should declare /en/about/ as its English version. Otherwise, the tags look correct individually but the relationship is broken.

I'd build a small page index from the generated HTML and check each relationship:

// pages is a Map keyed by absolute canonical URL
for (const [url, page] of pages) {
  if (page.canonical !== url) {
    throw new Error(`Incorrect canonical: ${url}`);
  }

  for (const [lang, alternateUrl] of Object.entries(page.hreflang)) {
    if (lang === "x-default") continue;

    const target = pages.get(alternateUrl);

    if (!target || target.hreflang[page.locale] !== url) {
      throw new Error(`Broken hreflang relationship: ${url} -> ${alternateUrl}`);
    }
  }
}

That assumes the page index contains the generated URLs, each page's locale, canonical URL and alternate links. I wouldn't require all four languages on every page unless every page actually has four translations.

Second, a passing GitHub Actions check and a Cloudflare preview deployment are two different things. Cloudflare Pages can deploy preview branches automatically, even while a PR's checks are failing.

For a private project, I'd use this sequence:

1. Build the static output in GitHub Actions, without deployment credentials.
2. Run the reciprocal hreflang/canonical check, validate sitemap and robots.txt, check local links, parse JSON-LD and check image markup.
3. Run Lighthouse CI against a local server, keeping performance warnings separate from critical SEO failures.
4. Make the audit a required check on main, with direct pushes restricted.
5. Deploy previews only from approved branches, and protect preview access with Cloudflare Access if the content isn't meant to be public.

One more small distinction: parsing JSON-LD confirms valid JSON, not necessarily valid Schema.org properties. I'd report those as separate checks.

This gives you a predictable PR gate without granting Cloudflare credentials to the validation job or touching production before review.

[NavidZamanKhan]

Hi! I'd recommend running SEO checks on the generated static files through GitHub Actions before merging anything into your production branch.

Here's how I'd approach it:

1. Use HTML-Validate to catch invalid HTML, missing image attributes, and structural issues.
2. Use Linkinator to detect broken internal links across generated pages.
3. Write a small Node.js script to check that every language version has a self-referencing canonical URL and reciprocal hreflang links.
4. Validate JSON-LD syntax and required structured-data properties. Also check that sitemap.xml and robots.txt reference the correct URLs.
5. Use Lighthouse CI to catch mobile performance and accessibility regressions.

For a basic GitHub Actions workflow, you can start with:

name: SEO Checks
on: [pull_request]

jobs:
  seo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run build
      - run: npx html-validate "dist/**/*.html"
      - run: npx linkinator ./dist --recurse

Replace dist with your actual build directory.

Cloudflare Pages can automatically generate preview deployments for pull requests without affecting production.

You can also configure required status checks on your main branch, provided your GitHub plan supports branch protection for private repositories.

Useful resources:

https://github.com/JustinBeckwith/linkinator

https://html-validate.org/

https://github.com/GoogleChrome/lighthouse-ci

https://developers.cloudflare.com/pages/configuration/preview-deployments/

One important detail: preview deployments can happen before CI finishes. Required checks will protect merging, but preventing production deployment also requires controlling how your production branch is updated.

Hope this helps!