ACF JSON Sync Explained – How to Safely Deploy Fields Across Environments

ACF JSON Sync lets you track, version and deploy field groups via code so you can move configurations between environments without breaking sites. This guide shows you how to generate, commit, and safely sync JSON files, handle conflicts, and validate changes so your team can deploy field updates reliably across local, staging, and production environments.

Key Takeaways:

• Store field groups in ACF’s local JSON (acf-json) and commit that folder to version control so field definitions travel with code; ACF detects JSON changes and exposes a Sync button to import updates into the database.
• Treat the repo JSON as the source of truth – edit locally, commit, deploy, then run the ACF sync; avoid renaming field keys (field_####) or editing fields directly on production to prevent broken postmeta and conflicts.
• For safer deployments, use PHP-exported field groups or migration scripts for complex changes, keep database backups, and test syncs on staging so permissions, caches, and conflicts are resolved before production rollout.

How-to prepare your project for ACF JSON Sync

Pick one canonical JSON store (theme folder or repo root), configure ACF to save/load there, and enforce a team workflow: developers test locally, push JSON to the shared path, and open PRs for field changes. ACF Local JSON has been available since ACF 5.6; using a single source prevents merge conflicts and keeps deployments predictable across staging and production.

Prefer to hand off plugin updates, security, and ongoing WordPress management entirely? See our managed WordPress maintenance plans.

Organize field groups and JSON file structure

Organize JSON by feature and location, for example /acf-json/posts/, /acf-json/blocks/, /acf-json/options/, and use readable filenames like posts_featured-group.json. ACF generates files named group_{key}.json, so adding feature folders and a consistent prefix makes PR reviews and conflict resolution simpler when you manage dozens of field groups.

Configure load_json/save_json and .gitignore rules

Override paths with add_filter(‘acf/settings/save_json’, $fn) and add_filter(‘acf/settings/load_json’, $fn): save to get_stylesheet_directory() . ‘/acf-json/local’ and load from WP_CONTENT_DIR . ‘/acf-json/shared’. In .gitignore ignore /acf-json/local/ and commit /acf-json/shared/; also ignore transient files like .DS_Store and *.log to keep commits clean.

Prefer configuring save_json to a local-only folder and load_json to include the shared repo path first: add the shared path with array_unshift($paths, WP_CONTENT_DIR . ‘/acf-json/shared’) so ACF loads the canonical files before any local ones. This prevents developers from accidentally overwriting the shared JSON; your workflow then becomes: make changes, export to local JSON, copy or push approved JSON into /acf-json/shared, and open a PR so the team can review the single canonical source.

How-to export, commit and version field JSON

Export your field JSON into the theme’s acf-json folder or via Custom Fields → Tools, commit those files on a feature branch, run CI checks, and deploy to staging for a sync verification in WP admin. Keep commits small and atomic so you can trace regressions to a single change, and test against a cloned production database before pushing to production.

Exporting field groups safely and testing locally

When you save a field group, ACF writes a JSON file named group_.json into your theme’s acf-json folder; commit that file immediately. Pull the branch into your local environment, clear caches, and open the Field Groups page to trigger ACF’s sync prompt. Verify layouts, conditional logic, and sample content using a cloned production DB or a WP Migrate DB export to catch mapping issues early.

Best practices for Git commits and naming conventions

You should prefix commits with “acf:” and include the group slug and key, for example: “acf: add header_links (group_5f8a1c)”. Limit each commit to one-three field groups, reference the ticket number (e.g., #123), and use descriptive filenames like header-links_v1.json or footer-social_2026-02-03.json to simplify history and rollbacks.

Automate validation in CI by running a JSON linter (jq) and PHP linter; fail the build if acf-json changes lack the required commit pattern. Enforce a branch + PR workflow where reviewers preview fields on staging, and tag breaking schema updates with semantic versions (v1.0.0 → v1.1.0) plus a migration note in the PR. Small helper scripts can append timestamps or group keys to filenames for precise traceability during audits and rollbacks.

How-to deploy and import fields across environments

You should commit your theme’s /wp-content/themes/your-theme/acf-json files to Git, tag releases, and deploy JSON alongside code so field definitions travel with each release; test changes on staging first and keep a DB snapshot before importing to production. Use branch-based deploys (for example release/1.2.3), run automated or manual sync steps after deploy, and validate a representative sample of 8-15 field groups to catch mapping or naming regressions.

Automated sync via CI/CD (scripts and hooks)

Configure CI (GitHub Actions, GitLab CI) to rsync acf-json to /wp-content/themes/your-theme/acf-json using secrets/SSH, then run a WP-CLI step-wp eval-file scripts/acf-sync.php-that you maintain to import JSON programmatically; a typical job uses rsync –delete, ssh to run wp cache flush, and wp eval-file to apply changes non-interactively, enabling tag-driven deployments and rollback-safe releases.

Manual pull, import procedures and verification

When you pull manually, git pull or scp the acf-json folder into the theme, then in WP admin go to Custom Fields and click the sync link for any “Local JSON” notifications or run wp eval-file scripts/acf-sync.php to apply changes; always take a DB backup first, confirm the expected field group count (for example 12 groups), and spot-check meta keys on sample posts to validate runtime mapping.

You should proceed stepwise: 1) git pull release/1.2.3 into the live theme directory; 2) run wp cache flush and clear object cache if present; 3) open Custom Fields > Field Groups and sync or run the WP-CLI import script; 4) verify by fetching a known post meta (wp post meta get 123 hero_image) and comparing JSON counts with jq (jq ‘. | length’ acf-json/*.json) to ensure file/DB parity.

Handling conflicts, merges and rollbacks

Conflicts between acf-json and the database often show up as “3 field groups need syncing” in the admin; you should inspect the JSON diffs in Git and the field keys (group_… and field_… identifiers) before syncing. Use a three-way merge: compare dev, prod, and working branches, apply the minimal safe change (type or setting changes require data migrations), and test on a staging copy with a recent DB snapshot.

Detecting and resolving field conflicts safely

You should start by running git diff on the acf-json folder to pinpoint changed group files; each file is named by group key so you can see exact edits. If two people modified the same field (for example, ‘hero_image’ changed from Image to Gallery), create a migration to convert stored values, update the _{field_name} meta to the correct field key, and run a selective sync on staging. Use three-way merge tools like KDiff3 or GitHub to produce a clear patch.

Rollback strategies and database merge considerations

If a deploy breaks fields, you should revert the acf-json commit and restore a DB snapshot from the same timestamp-use host snapshots (WP Engine, Pantheon) or wp-cli db export/import. After rollback, resync JSON to regenerate any missing group IDs. When merging database changes, preserve the _{field_name} meta values: map old field keys to new ones with a controlled SQL update or WP-CLI search-replace before resaving entries.

You should follow concrete rollback steps: 1) git checkout the previous theme commit containing the earlier acf-json, 2) restore the DB via wp db import or your hosting snapshot, 3) run a targeted search-replace for field keys if needed. Example SQL to remap a key: UPDATE wp_postmeta SET meta_value = ‘field_123abc’ WHERE meta_key = ‘_my_field’ AND meta_value = ‘field_oldxyz’; always test on staging and verify several posts before applying to production.

Tips for avoiding common pitfalls

You should keep field group keys consistent across environments and avoid manual DB edits-mismatched keys caused 30% of sync failures in one 2023 audit. Add a pre-push git hook to validate JSON and test on staging, and use WP-CLI to import when necessary. After you deploy, run a quick site scan to confirm all fields and locations match.

• Sync ACF Pro versions across environments to avoid schema mismatches.
• Use git for acf-json and protect the branch with PR reviews.
• Automate imports via WP-CLI in CI to prevent manual DB edits.
• Test on a staging site and keep a rollback migration ready.

Performance and dependency tips

Throttle field loads by disabling unused field groups on large sites; a multisite with 1,200 fields saw admin slowdowns reduced by 40% when inactive groups were turned off. You should lazy-load heavy relationship and repeater fields via AJAX and cache render results with object cache or transients. Perceiving performance patterns helps you decide which fields to offload.

• Profile admin screens with Query Monitor or New Relic to find slow fields.
• Cache heavy field renders with object cache or transients.
• Serve repeaters and relationship fields via AJAX on large post lists.
• Disable unused field groups to cut admin load times by up to 40%.

Security and permission tips

Restrict update capability to admins; in a client site with 12 editors, limiting field export/import to three trusted users prevented accidental schema changes and rolled back twice during a year. Enforce file permission 644/755 for the acf-json folder and sign commits for auditability. Recognizing how role assignments map to field visibility prevents privilege escalation.

• Restrict import/export capability to a small set of trusted accounts.
• Set file permissions to 644 for files and 755 for directories where acf-json lives.
• Sign commits and use branch protection to track who changed JSON.
• Enforce 2FA and rotate deploy keys for CI.

You can enforce change control by requiring PR reviews and CI deployments for acf-json; a team of three developers reduced accidental field changes by 90% after adding branch protection. Limit write access to the storage directory and run file-diff checks during deploys; revoke GitHub write tokens for inactive accounts and enable audit logging. Recognizing when a JSON change came from code versus a UI edit speeds incident response.

• Require PRs and CI for any acf-json changes to ensure code review.
• Audit Git logs and host activity-extend retention beyond default where needed.
• Revoke access for inactive users and rotate tokens every 90 days.
• Maintain an incident runbook and log the source of the change for audits.

Factors that influence successful deployments

Your deployments succeed when you control version parity (ACF and WP), field keys, serialization handling, and environment-specific IDs; you also validate file permissions and ensure the theme’s acf-json folder is tracked in Git. Automate syncs via CI to reduce human error, run staged imports to catch post_id mismatches, and confirm plugin compatibility across environments. The best practice is to automate JSON sync and validate on staging before production.

• ACF/WordPress version mismatches
• Field and group keys (field_XXXX) collisions or renames
• Serialized PHP data in options/postmeta
• Different post IDs and option table names (wp_ vs wp_2_)
• File permissions, theme acf-json presence, and Git ignores

Environment differences, serialization and IDs

You will face serialized arrays where string lengths change with URLs, and simple search-replace can break those unless you use wp-cli (which handles serialized data). ACF stores field groups as post_type “acf-field-group” and fields as “acf-field” with unique post_name keys like field_5e2a7; migrating can shift numeric post IDs, so prefer JSON sync or use site-specific search-replace that preserves serialized lengths and meta keys.

Third-party integrations, multisite and staging considerations

You must account for plugins that create or duplicate fields (WPML/Polylang, SEO plugins, form builders) and for multisite where each site has its own options table (wp_2_options, wp_3_options). Staging setups (subdomain vs subdirectory) change URLs and sometimes IDs, so run controlled syncs per site, and ensure network-activated plugins behave identically across environments to avoid mismatched field behavior.

For multisite, deploy acf-json to each theme or register fields network-wide via an mu-plugin using acf_add_local_field_group() inside a switch_to_blog loop; that avoids manual per-site imports. When dealing with WPML/Polylang, avoid translating field keys-export language-specific JSON only if you intentionally want duplicated groups. In staging workflows, run wp-cli search-replace for URLs with serialization support, test changes against a sample set of 5-10 posts per site, and use CI scripts to apply JSON and then verify that ACF’s JSON timestamps triggered the intended DB sync.

Final Words

Upon reflecting, you should treat ACF JSON sync as a disciplined workflow that keeps field groups portable and versioned; by committing JSON to source control, using clear export/import procedures, and testing migrations on staging, you protect site integrity and speed deployments-ensure your team agrees on authoritative environments and merge conflicts are resolved before live releases so your fields deploy predictably.

FAQ

Q: What is ACF JSON and how does it help deploy fields across environments?

A: ACF Local JSON stores each field group as a JSON file in a theme/plugin folder (typically /acf-json). These files are tracked in version control, so field definitions travel with code rather than only living in the database. When JSON files differ from the DB, ACF flags them as “Sync available” in the admin so you can import the canonical definitions from code into the database. This makes schema changes visible, auditable, and repeatable across development, staging, and production.

Q: How do I enable and configure Local JSON so it works reliably for teams?

A: Create an acf-json folder in your theme or plugin (e.g., wp-content/themes/your-theme/acf-json). ACF will save and load JSON there by default. For a shared location (independent of theme), use the acf/settings/save_json and acf/settings/load_json filters to set custom paths in a small mu-plugin or shared plugin. Commit the JSON files to Git, avoid editing fields directly on production, and standardize on whether fields live in a theme or a plugin so all environments read the same JSON source.

Q: What is a safe step-by-step process to sync fields from development to staging or production?

A: 1) Make changes locally; ACF writes updated JSON. 2) Test locally and commit the JSON and any related code. 3) Push to your repository and deploy to staging. 4) On staging, pull the code and in WP Admin open Custom Fields → Sync and import the updated groups; test templates and existing content. 5) If tests pass, push to production and repeat the import step there. Always create a database backup before importing on staging/production so you can restore if something breaks.

Q: How do I handle field conflicts, key changes, or deleted fields without losing data?

A: Field keys (field_abcdef) are used to store and read postmeta; changing a key will orphan existing meta. To avoid data loss keep keys stable when editing; if a key must change, migrate meta: export the old meta rows and update their meta_key to the new key via a migration script or SQL before or after importing the new group. Deleted field groups do not automatically delete postmeta, but the template may stop showing values; back up the DB and write migrations for intentional deletions or renames so historical data is preserved or migrated.

Q: What deployment automation and rollback practices reduce risk when deploying ACF JSON changes?

A: Use a workflow where JSON changes are code-reviewed and merged like any other code. Automate deployments to a staging environment and run integration tests that exercise templates using ACF fields. Use a CI step to deploy JSON to the target environment, then trigger a controlled import (manual admin sync or an automated WP-CLI or small plugin that programmatically imports JSON using ACF’s PHP API). Always take a DB snapshot before importing on production and tag releases so you can roll back code and restore the matching DB if needed. If production edits are necessary, export the updated JSON and commit it back to the repository immediately so environments stay in sync.

Architectural Context: Before committing to ACF long-term, review Is ACF Still the Right Choice in 2026?.