Cloudflare Pages

Cloudflare Pages permet de déployer des sites statiques (Astro, Next.js, etc.) sur le réseau edge de Cloudflare avec CI/CD intégré ou via Wrangler.

Table des matières

Concepts
Prérequis
Initialisation d’un projet
Configuration Wrangler
Déploiement manuel
CI/CD avec Gitea Actions
Environnements
Troubleshooting

1. Concepts

Pages vs Workers

Aspect	Pages	Workers
Usage	Sites statiques, SSG, SSR	API, fonctions serverless
Build	Côté Cloudflare ou local	Local uniquement
Output	Fichiers HTML/CSS/JS	Code JavaScript
Commande	`wrangler pages deploy`	`wrangler deploy`

Flux de déploiement

sequenceDiagram
    participant Dev as Développeur
    participant Gitea as Gitea
    participant Runner as Runner CI
    participant CF as Cloudflare

    Dev->>Gitea: git push main
    Gitea->>Runner: Déclenche workflow
    Runner->>Runner: bun install
    Runner->>Runner: bun run build (astro build)
    Runner->>CF: wrangler pages deploy dist
    CF->>CF: Upload des fichiers
    CF-->>Runner: URL de déploiement
    Note over CF: Disponible sur<br/>projet.pages.dev

2. Prérequis

2.1. Installation de Wrangler

# Avec bun (recommandé)
bun add -d wrangler

# Avec npm
npm install -D wrangler

2.2. Authentification

bun wrangler login

Cette commande :

Ouvre un navigateur pour l’authentification OAuth
Stocke les credentials dans ~/.wrangler/config/default.toml
Affiche “Successfully logged in” si réussi

2.3. Vérifier la connexion

bun wrangler whoami

Output attendu :

⛅️ wrangler 4.x.x
Getting User settings...
👋 You are logged in with an OAuth Token, associated with the email: votre@email.com

3. Initialisation d’un projet

3.1. Créer le projet sur Cloudflare

bun wrangler pages project create <nom-du-projet>

Exemple :

bun wrangler pages project create mindlet-doc

Output :

✔ Enter the production branch name: › main
✨ Successfully created the 'mindlet-doc' project.
It will be available at https://mindlet-doc.pages.dev/

3.2. Récupérer la configuration

Si vous avez déjà un projet Pages existant, téléchargez sa configuration :

bun wrangler pages download config <nom-du-projet>

Exemple :

bun wrangler pages download config mindlet-doc

Cela crée un fichier wrangler.toml avec la configuration du projet.

4. Configuration Wrangler

4.1. Structure du fichier

Créez wrangler.toml ou wrangler.jsonc à la racine du projet :

wrangler.toml (recommandé) :

name = "mindlet-doc"
compatibility_date = "2026-01-17"
compatibility_flags = ["nodejs_compat"]
pages_build_output_dir = "./dist"

[observability]
enabled = true

[env.production]
# Configuration spécifique à la production

wrangler.jsonc (alternative) :

{
  "name": "mindlet-doc",
  "compatibility_date": "2026-01-17",
  "compatibility_flags": ["nodejs_compat"],
  "pages_build_output_dir": "./dist",
  "observability": {
    "enabled": true
  }
}

4.2. Options importantes

Option	Description	Exemple
`name`	Nom du projet Pages	`"mindlet-doc"`
`pages_build_output_dir`	Dossier de build à déployer	`"./dist"`
`compatibility_date`	Date de compatibilité Workers	`"2026-01-17"`
`compatibility_flags`	Flags de compatibilité	`["nodejs_compat"]`

4.3. Bindings (optionnel)

Pour utiliser KV, D1, ou autres services :

[[kv_namespaces]]
binding = "SESSION"
id = "xxxxx"

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "xxxxx"

5. Déploiement manuel

5.1. Build du projet

bun run build

Pour Astro, cela exécute astro build et génère les fichiers dans dist/.

5.2. Déployer

Méthode 1 : Avec configuration wrangler

bun wrangler pages deploy dist

Méthode 2 : Sans fichier de configuration

bun wrangler pages deploy dist --project-name=mindlet-doc

5.3. Output du déploiement

✨ Success! Uploaded 105 files (2.67 sec)
✨ Compiled Worker successfully
✨ Uploading Worker bundle
✨ Deployment complete! Take a peek over at https://abc123.mindlet-doc.pages.dev

Chaque déploiement génère une URL unique (abc123.mindlet-doc.pages.dev) en plus de l’URL de production (mindlet-doc.pages.dev).

6. CI/CD avec Gitea Actions

6.1. Secrets requis

Configurez ces secrets dans Gitea (Settings → Actions → Secrets) :

Secret	Description	Comment l’obtenir
`CLOUDFLARE_API_TOKEN`	Token API avec permissions Pages	Dashboard Cloudflare → API Tokens
`CLOUDFLARE_ACCOUNT_ID`	ID de votre compte	Dashboard → Overview → Account ID

6.2. Créer un API Token

Aller sur Cloudflare Dashboard → API Tokens
Cliquer Create Token
Utiliser le template Edit Cloudflare Workers ou créer un custom :
- Permissions :
  - Account → Cloudflare Pages → Edit
  - Account → Workers Scripts → Edit
- Account Resources : Include → Votre compte
Copier le token (affiché une seule fois)

6.3. Workflow de déploiement

Créez .gitea/workflows/deploy.yml :

name: Deploy Documentation

on:
  push:
    branches: [main]

jobs:
  deploy:
    if: gitea.ref == 'refs/heads/main' && gitea.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest

      - name: Install dependencies
        run: bun install --frozen-lockfile

      - name: Build
        run: bun run build

      - name: Deploy to Cloudflare Pages
        run: bunx wrangler pages deploy dist --project-name=mindlet-doc
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

6.4. Workflow multi-environnements

Pour déployer en staging et production :

name: CI/CD

on:
  push:
    branches: [main, staging]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest
      - run: bun install --frozen-lockfile
      - run: bun run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

  deploy-staging:
    needs: build
    if: gitea.ref == 'refs/heads/staging' && gitea.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/
      - run: bunx wrangler pages deploy dist --project-name=mindlet-doc --branch=staging
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

  deploy-production:
    needs: build
    if: gitea.ref == 'refs/heads/main' && gitea.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/
      - run: bunx wrangler pages deploy dist --project-name=mindlet-doc
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

7. Environnements

7.1. Branches de preview

Chaque branche déployée obtient une URL unique :

main → mindlet-doc.pages.dev (production)
staging → staging.mindlet-doc.pages.dev
feature-x → feature-x.mindlet-doc.pages.dev

7.2. Domaines personnalisés

Aller dans Cloudflare Dashboard → Pages → votre projet → Custom domains
Ajouter le domaine (ex: docs.mindlet.app)
Configurer le DNS :
- Type: CNAME
- Name: docs
- Target: mindlet-doc.pages.dev

8. Troubleshooting

Problème : “Project not found”

Symptôme : Error: Project not found

Cause : Le projet n’existe pas ou le nom est incorrect.

Solution :

# Lister les projets existants
bun wrangler pages project list

# Créer le projet s'il n'existe pas
bun wrangler pages project create <nom>

Problème : Pas de fichier wrangler.toml

Symptôme : Wrangler demande interactivement le projet à chaque déploiement.

Cause : Absence de fichier de configuration.

Solution :

# Télécharger la config depuis Cloudflare
bun wrangler pages download config <nom-du-projet>

# Ou créer manuellement wrangler.toml

Problème : “Authentication error”

Symptôme : Error: Authentication error

Cause : Token expiré ou invalide.

Solution :

# Se reconnecter
bun wrangler logout
bun wrangler login

# Vérifier
bun wrangler whoami

Problème : Build échoue dans CI

Symptôme : Le job CI échoue lors du build.

Causes possibles :

Dépendances manquantes
Version Node/Bun incompatible
Variables d’environnement manquantes

Solution :

# Vérifier les versions dans le workflow
- uses: oven-sh/setup-bun@v1
  with:
    bun-version: latest  # ou une version fixe

# Ajouter les variables d'env si nécessaires
- run: bun run build
  env:
    PUBLIC_API_URL: ${{ vars.PUBLIC_API_URL }}

Références

Ressource	Lien
Cloudflare Pages Docs	https://developers.cloudflare.com/pages/
Wrangler Commands	https://developers.cloudflare.com/workers/wrangler/commands/
Pages Functions	https://developers.cloudflare.com/pages/functions/
Astro + Cloudflare	https://docs.astro.build/en/guides/deploy/cloudflare/