A favicon can be visually correct and still fail in production because of a wrong MIME type, missing file, unsupported dimension, stale reference, or incomplete web app manifest. This reusable CI checklist shows how to validate favicon assets before deployment, so icon changes are reviewed like other release-critical files rather than discovered in a browser tab after launch.
Overview
Automated favicon validation is a small quality gate for a website’s visual identity. The goal is not to test every browser manually on every commit. It is to catch predictable asset and integration errors early: files that are absent, unreadable, incorrectly sized, served under the wrong content type, or referenced by HTML and manifest files that no longer match the repository.
A practical favicon CI check usually has four layers:
- File checks: Confirm that every expected icon exists, is readable, and has the intended extension and format.
- Image checks: Inspect dimensions, color mode, transparency, and whether the file is actually a valid image.
- Reference checks: Compare HTML, web app manifest, framework configuration, and asset paths with the files committed to the repository.
- Deployment checks: Verify that generated URLs, MIME types, and cache-busting paths point to the new asset rather than an old or missing one.
Keep the expected asset list explicit. A small repository manifest makes the policy reviewable and prevents a workflow from silently passing simply because it found one valid icon.
{
"icons": [
{ "path": "public/favicon.ico", "format": "ico", "minWidth": 16, "minHeight": 16 },
{ "path": "public/favicon-32.png", "format": "png", "width": 32, "height": 32 },
{ "path": "public/apple-touch-icon.png", "format": "png", "width": 180, "height": 180 },
{ "path": "public/icon-192.png", "format": "png", "width": 192, "height": 192 },
{ "path": "public/icon-512.png", "format": "png", "width": 512, "height": 512 }
]
}The exact set should reflect your application. A simple website may need only an ICO or PNG favicon. A progressive web app, multi-domain product, or branded platform may maintain additional icons. For background on choosing assets, compare this favicon size guide with the requirements of your own templates and deployment targets.
Checklist by scenario
For every pull request that changes an icon
- Check that every path in the asset manifest exists.
- Reject empty files, corrupted images, and files whose extension does not match their detected format.
- Validate required dimensions. A square icon should have equal width and height unless a specific integration permits another shape.
- Confirm that transparent artwork has enough contrast against the backgrounds where the icon will appear.
- Inspect the diff for accidental replacement of production assets with a local, draft, or environment-specific file.
- Run a reference scan against the document head and manifest files.
For a new website or framework migration
- List every location where the framework may serve identity assets: static directories, generated metadata, HTML templates, and manifest configuration.
- Choose one canonical location for source assets and document which files are generated.
- Check that build output preserves filenames, dimensions, and formats.
- Test both a clean build and an incremental build. An incremental build can hide stale generated files that are absent from a clean deployment.
- Verify that the deployed HTML references the intended environment path rather than a local root, development port, or temporary asset directory.
For a rebrand or icon replacement
- Replace the complete icon set, not only the file most visible in a browser tab.
- Search the repository and built output for the previous filename, title, or cache-busting query string.
- Confirm that the new icon is used consistently across the favicon link, manifest entries, touch icon references, and any platform-specific metadata your project maintains.
- Use a deliberate versioned filename or query parameter if your deployment strategy requires cache invalidation. Do not create multiple competing references without a reason.
- Run a post-deployment smoke check against the public URL after the release gate passes.
This favicon rebrand checklist is useful when the change affects an established site with existing cached assets.
For multiple domains or environments
- Define whether development, staging, and production use the same icon or distinct environment markers.
- Validate that each host serves the correct path and does not inherit a relative URL from another environment.
- Check subdomain-specific manifests and templates separately.
- Ensure a deployment to one domain cannot overwrite or reference another domain’s asset directory.
A shared asset manifest and a parameterized URL test can make this repeatable. See the guide to a multi-site favicon system for a broader organization model.
What to double-check
Dimensions and image content
Dimensions should be explicit, not inferred from a filename such as icon-32.png. A validation script should read the image metadata and compare it with the expected width and height. For flexible formats such as ICO, decide whether the file must contain a particular embedded size or a set of sizes. Do not treat a successful file open as proof that the asset meets the product requirement.
Transparency deserves a separate rule. If an icon is intended to have a transparent background, check that the image includes an alpha channel and that the artwork remains recognizable on light and dark surfaces. If transparency is not intended, reject unexpected alpha data or document why it is allowed. The dark mode and high-density favicon checklist provides useful visual review prompts.
MIME types and HTTP responses
File extensions are not HTTP headers. In a deployed smoke test, request each public icon and check for a successful response, an appropriate Content-Type, and a non-empty body. Also confirm that redirects are intentional and that the asset is not being returned as an HTML error page with a successful-looking status.
HTML and manifest references
Reference validation should catch both missing files and orphaned files. A link to /favicon-32.png should resolve to a committed or generated asset, while an old /favicon-old.png should not remain in a template after a rebrand. Parse structured manifest files where possible instead of relying only on regular expressions; use text searches as a complementary check for templates and generated output.
Cache-busting paths
Cache invalidation is a release concern, not merely a browser-testing concern. If the build emits hashed filenames, validate that the HTML and manifest use the current build output. If the project uses stable names, ensure the deployment process can replace the file atomically and that references do not point to an obsolete version. A CI job cannot prove every intermediary cache has refreshed, but it can prevent stale paths from being published.
Common mistakes
- Testing only the source directory: The source asset may be valid while the build copies, renames, or drops it incorrectly. Test the generated output too.
- Checking only HTTP status: A page or error document can be returned with a successful response. Inspect the content type and image decodability.
- Assuming one favicon covers every integration: Browser tabs, bookmarks, touch icons, manifests, and application shells may use different references.
- Allowing warnings to pass indefinitely: Treat missing required files, invalid dimensions, and broken references as failures. Reserve warnings for documented, intentional exceptions.
- Relying on a filename for dimensions: Read actual image metadata.
- Using a single visual snapshot as the whole test: Automated checks catch structural errors; a human review is still valuable for legibility, contrast, and brand recognition. The favicon accessibility and brand recognition audit covers that complementary review.
- Ignoring generated files: Decide whether generated icons are committed, built in CI, or produced by a release step. Ambiguity makes missing-file failures difficult to diagnose.
Keep the validator close to the code it protects. A repository script such as npm run check:favicons can be run locally and in CI, while the workflow file supplies the release gate. The platform syntax may differ, but the sequence is consistent: install dependencies, build if needed, validate source and output assets, then run a deployed smoke check when the environment is available.
When to revisit
Review this favicon CI policy before a major release, seasonal planning cycle, rebrand, framework migration, domain change, or deployment-platform change. Revisit it whenever a new icon type is introduced, a build tool changes asset handling, or a manifest and metadata strategy is redesigned. It is also worth checking after a browser or platform testing review reveals an icon that works locally but fails in production.
At each review, ask:
- Does the asset manifest still describe every icon the product actually uses?
- Are dimensions, transparency, and formats still appropriate for the current surfaces?
- Does the validator inspect both source files and production-like output?
- Do HTML and manifest references resolve without stale or environment-specific paths?
- Does the deployed smoke test verify MIME type, response content, and cache-busting behavior?
- Can a developer run the same checks locally before opening a pull request?
Start with four release gates today: required files exist, image metadata matches the manifest, references resolve, and deployed responses have the expected content type. Then add environment-specific checks only when your application needs them. This keeps favicon linting fast enough for every change while giving your website’s smallest identity assets the same dependable workflow as the rest of the release.
For broader cross-browser and bookmark coverage after CI passes, continue with the favicon testing checklist.