Cloudflare Rules come in three primary varieties, each serving distinct purposes in optimizing and securing your GitHub Pages website. Page Rules represent the original and most widely used rule type, allowing you to control Cloudflare settings for specific URL patterns. These rules enable features like custom cache behavior, SSL configuration, and forwarding rules without writing any code.
Transform Rules represent a more recent addition to Cloudflare's rules ecosystem, providing granular control over request and response modifications. Unlike Page Rules that control Cloudflare settings, Transform Rules directly modify HTTP messages—changing headers, rewriting URLs, or modifying query strings. This capability makes them ideal for implementing redirects, canonical URL enforcement, and header management.
Firewall Rules provide security-focused functionality, allowing you to control which requests can access your site based on various criteria. Using Firewall Rules, you can block or challenge requests from specific countries, IP addresses, user agents, or referrers. This layered security approach complements GitHub Pages' basic security model, protecting your site from malicious traffic while allowing legitimate visitors uninterrupted access.
| Rule Type | Primary Function | Use Cases | Configuration Complexity |
|---|---|---|---|
| Page Rules | Control Cloudflare settings per URL pattern | Caching, SSL, forwarding | Low |
| Transform Rules | Modify HTTP requests and responses | URL rewriting, header modification | Medium |
| Firewall Rules | Security and access control | Blocking threats, rate limiting | Medium to High |
Page Rules serve as the foundation of Cloudflare optimization for GitHub Pages, allowing you to customize how Cloudflare handles different sections of your website. The most common application involves cache configuration, where you can set different caching behaviors for static assets versus dynamic content. For GitHub Pages, this typically means aggressive caching for CSS, JavaScript, and images, with more conservative caching for HTML pages.
Another essential Page Rules strategy involves SSL configuration. While GitHub Pages supports HTTPS, you might want to enforce HTTPS connections, enable HTTP/2 or HTTP/3, or configure SSL verification levels. Page Rules make these configurations straightforward, allowing you to implement security best practices without technical complexity. The "Always Use HTTPS" setting is particularly valuable, ensuring all visitors access your site securely regardless of how they arrive.
Forwarding URL patterns represent a third key use case for Page Rules. GitHub Pages has limitations in URL structure and redirection capabilities, but Page Rules can overcome these limitations. You can implement domain-level redirects (redirecting example.com to www.example.com or vice versa), create custom 404 pages, or set up temporary redirects for content reorganization—all through simple rule configuration.
# Example Page Rules configuration for GitHub Pages
# Rule 1: Aggressive caching for static assets
URL Pattern: example.com/assets/*
Settings:
- Cache Level: Cache Everything
- Edge Cache TTL: 1 month
- Browser Cache TTL: 1 week
# Rule 2: Standard caching for HTML pages
URL Pattern: example.com/*
Settings:
- Cache Level: Standard
- Edge Cache TTL: 1 hour
- Browser Cache TTL: 30 minutes
# Rule 3: Always use HTTPS
URL Pattern: *example.com/*
Settings:
- Always Use HTTPS: On
# Rule 4: Redirect naked domain to www
URL Pattern: example.com/*
Settings:
- Forwarding URL: 301 Permanent Redirect
- Destination: https://www.example.com/$1
Transform Rules provide precise control over HTTP message modification, bridging the gap between simple Page Rules and complex Workers. For GitHub Pages, Transform Rules excel at implementing URL normalization, header management, and query string manipulation. Unlike Page Rules that control Cloudflare settings, Transform Rules directly alter the requests and responses passing through Cloudflare's network.
URL rewriting represents one of the most powerful applications of Transform Rules for GitHub Pages. While GitHub Pages requires specific file structures (either file extensions or index.html in directories), Transform Rules can create user-friendly URLs that hide this underlying structure. For example, you can transform "/about" to "/about.html" or "/about/index.html" seamlessly, creating clean URLs without modifying your GitHub repository.
Header modification is another valuable Transform Rules application. You can add security headers, remove unnecessary headers, or modify existing headers to optimize performance and security. For instance, you might add HSTS headers to enforce HTTPS, set Content Security Policy headers to prevent XSS attacks, or modify caching headers to improve performance—all through declarative rules rather than code.
| Rule Type | Condition | Action | Result |
|---|---|---|---|
| URL Rewrite | When URI path is "/about" | Rewrite to URI "/about.html" | Clean URLs without extensions |
| Header Modification | Always | Add response header "X-Frame-Options: SAMEORIGIN" | Clickjacking protection |
| Query String | When query contains "utm_source" | Remove query string | Clean URLs in analytics |
| Canonical URL | When host is "example.com" | Redirect to "www.example.com" | Consistent domain usage |
Firewall Rules provide essential security layers for GitHub Pages websites, which otherwise rely on basic GitHub security measures. These rules allow you to create sophisticated access control policies based on request properties like IP address, geographic location, user agent, and referrer. By blocking malicious traffic at the edge, you protect your GitHub Pages origin from abuse and ensure resources are available for legitimate visitors.
Geographic blocking represents a common Firewall Rules pattern for restricting content based on legal requirements or business needs. If your GitHub Pages site contains content licensed for specific regions, you can use Firewall Rules to block access from unauthorized countries. Similarly, if you're experiencing spam or attack traffic from specific regions, you can implement geographic restrictions to mitigate these threats.
IP-based access control is another valuable security pattern, particularly for staging sites or internal documentation hosted on GitHub Pages. While GitHub Pages doesn't support IP whitelisting natively, Firewall Rules can implement this functionality at the Cloudflare level. You can create rules that allow access only from your office IP ranges while blocking all other traffic, effectively creating a private GitHub Pages site.
# Example Firewall Rules for GitHub Pages security
# Rule 1: Block known bad user agents
Expression: (http.user_agent contains "malicious-bot")
Action: Block
# Rule 2: Challenge requests from high-risk countries
Expression: (ip.geoip.country in {"CN" "RU" "KP"})
Action: Managed Challenge
# Rule 3: Whitelist office IP addresses
Expression: (ip.src in {192.0.2.0/24 203.0.113.0/24}) and not (ip.src in {192.0.2.100})
Action: Allow
# Rule 4: Rate limit aggressive crawlers
Expression: (cf.threat_score gt 14) and (http.request.uri.path contains "/api/")
Action: Managed Challenge
# Rule 5: Block suspicious request patterns
Expression: (http.request.uri.path contains "/wp-admin") or (http.request.uri.path contains "/.env")
Action: Block
Caching optimization represents one of the most impactful applications of Cloudflare Rules for GitHub Pages performance. While GitHub Pages serves content efficiently, its caching headers are often conservative, leaving performance gains unrealized. Cloudflare Rules allow you to implement aggressive, intelligent caching strategies that dramatically improve load times for repeat visitors and reduce bandwidth costs.
Differentiated caching strategies are essential for optimal performance. Static assets like images, CSS, and JavaScript files change infrequently and can be cached for extended periods—often weeks or months. HTML content changes more frequently but can still benefit from shorter cache durations or stale-while-revalidate patterns. Through Page Rules, you can apply different caching policies to different URL patterns, maximizing cache efficiency.
Cache key customization represents an advanced caching optimization technique available through Cache Rules (a specialized type of Page Rule). By default, Cloudflare uses the full URL as the cache key, but you can customize this behavior to improve cache hit rates. For example, if your site serves the same content to mobile and desktop users but with different URLs, you can create cache keys that ignore the device component, increasing cache efficiency.
| Content Type | URL Pattern | Edge Cache TTL | Browser Cache TTL | Cache Level |
|---|---|---|---|---|
| Images | *.(jpg|png|gif|webp|svg) | 1 month | 1 week | Cache Everything |
| CSS/JS | *.(css|js) | 1 week | 1 day | Cache Everything |
| HTML Pages | /* | 1 hour | 30 minutes | Standard |
| API Responses | /api/* | 5 minutes | No cache | Standard |
| Fonts | *.(woff|woff2|ttf|eot) | 1 year | 1 month | Cache Everything |
URL redirects and canonicalization are essential for SEO and user experience, and Cloudflare Rules provide robust capabilities in this area. GitHub Pages supports basic redirects through a _redirects file, but this approach has limitations in flexibility and functionality. Cloudflare Rules overcome these limitations, enabling sophisticated redirect strategies without modifying your GitHub repository.
Domain canonicalization represents a fundamental redirect strategy implemented through Page Rules or Transform Rules. This involves choosing a preferred domain (typically either www or non-www) and redirecting all traffic to this canonical version. Consistent domain usage prevents duplicate content issues in search engines and ensures analytics accuracy. The implementation is straightforward—a single rule that redirects all traffic from the non-preferred domain to the preferred one.
Content migration and URL structure changes are other common scenarios requiring redirect rules. When reorganizing your GitHub Pages site, you can use Cloudflare Rules to implement permanent (301) redirects from old URLs to new ones. This preserves SEO value and prevents broken links for users who have bookmarked old pages or discovered them through search engines. The rules can handle complex pattern matching, making bulk redirects efficient to implement.
# Comprehensive redirect strategy with Cloudflare Rules
# Rule 1: Canonical domain redirect
Type: Page Rule
URL Pattern: example.com/*
Action: Permanent Redirect to https://www.example.com/$1
# Rule 2: Remove trailing slashes from URLs
Type: Transform Rule (URL Rewrite)
Condition: ends_with(http.request.uri.path, "/") and
not equals(http.request.uri.path, "/")
Action: Rewrite to URI regex_replace(http.request.uri.path, "/$", "")
# Rule 3: Legacy blog URL structure
Type: Page Rule
URL Pattern: www.example.com/blog/*/*/
Action: Permanent Redirect to https://www.example.com/blog/$1/$2
# Rule 4: Category page migration
Type: Transform Rule (URL Rewrite)
Condition: starts_with(http.request.uri.path, "/old-category/")
Action: Rewrite to URI regex_replace(http.request.uri.path, "^/old-category/", "/new-category/")
# Rule 5: Force HTTPS for all traffic
Type: Page Rule
URL Pattern: *example.com/*
Action: Always Use HTTPS
Rules ordering significantly impacts their behavior when multiple rules might apply to the same request. Cloudflare processes rules in a specific order—typically Firewall Rules first, followed by Transform Rules, then Page Rules—with each rule type having its own evaluation order. Understanding this hierarchy is essential for creating predictable, effective rules configurations.
Within each rule type, rules are generally evaluated in the order they appear in your Cloudflare dashboard, from top to bottom. The first rule that matches a request triggers its configured action, and subsequent rules for that request are typically skipped. This means you should order your rules from most specific to most general, ensuring that specialized rules take precedence over broad catch-all rules.
Conflict resolution becomes important when rules might interact in unexpected ways. For example, a Transform Rule that rewrites a URL might change it to match a different Page Rule than originally intended. Similarly, a Firewall Rule that blocks certain requests might prevent Page Rules from executing for those requests. Testing rules interactions thoroughly before deployment helps identify and resolve these conflicts.
Effective monitoring ensures your Cloudflare Rules continue functioning correctly as your GitHub Pages site evolves. Cloudflare provides comprehensive analytics for each rule type, showing how often rules trigger and what actions they take. Regular review of these analytics helps identify rules that are no longer relevant, rules that trigger unexpectedly, or rules that might be impacting performance.
When troubleshooting rules issues, a systematic approach yields the best results. Begin by verifying that the rule syntax is correct and that the URL patterns match your expectations. Cloudflare's Rule Tester tool allows you to test rules against sample URLs before deploying them, helping catch syntax errors or pattern mismatches early. For deployed rules, examine the Firewall Events log or Transform Rules analytics to see how they're actually behaving.
Common rules issues include overly broad URL patterns that match unintended requests, conflicting rules that override each other unexpectedly, and rules that don't account for all possible request variations. Methodical testing with different URL structures, request methods, and user agents helps identify these issues before they affect your live site. Remember that rules changes can take a few minutes to propagate globally, so allow time for changes to take full effect before evaluating their impact.
By mastering Cloudflare Rules implementation for GitHub Pages, you gain powerful optimization and security capabilities without the complexity of writing and maintaining code. Whether through simple Page Rules for caching configuration, Transform Rules for URL manipulation, or Firewall Rules for security protection, these tools significantly enhance what's possible with static hosting while maintaining the simplicity that makes GitHub Pages appealing.