[Guide] Using the `ACF PRO` official install method with Bedrock/Trellis


  • For development, use an auth.json file in the Bedrock project folder – but it should not be committed to the repository, but rather added to .gitignore as it is a secret (the ACF PRO license), similar to the .env file.
    "http-basic": {
+        "connect.advancedcustomfields.com": {
+            "username": "[ACF PRO license key]",
+            "password": "https://[domain.tld]"
+        }

Use the ACF PRO license key as the username.

The password should be the site host (for which the license is active), including the protocol (https://example.com), not just the hostname or domain!
password must not be empty, it has to have some string value, and also it has to be a full URL with protocol, not just the hostname/domain, otherwise a HTTP authentication error will occur. Even if an Agency ACF PRO license is used with unlimited amount of sites, the password must be set to something (also see further below for setting a password to equal to each site host, which is needed for site-specific ACF PRO licenses).

  • Add the ACF PRO repository in composer.json:
  "repositories": [
+    {
+      "type":"composer",
+      "url":"https://connect.advancedcustomfields.com"
+    }
  • Require the ACF PRO plugin
    • Either by using the CLI:
      $ composer require wpengine/advanced-custom-fields-pro
    • Or by adding the require manually to composer.json (which the CLI command should do otherwise):
  "require": {
+  "wpengine/advanced-custom-fields-pro": "6.1.6"
  • (Optional) Clean up previous mechanisms for installing ACF PRO, e.g.
  "repositories": [
-   {
-       "type": "package",
-       "package": {
-         "name": "advanced-custom-fields/advanced-custom-fields-pro",
-         "version": "6.1.6",
-         "type": "wordpress-plugin",
-         "dist": {
-           "type": "zip",
-           "url": "https://connect.advancedcustomfields.com/index.php?a=download&p=pro&k={%PLUGIN_ACF_KEY}&t={%version}"
-         },
-         "require": {
-           "composer/installers": "^2",
-           "ffraenz/private-composer-installer": "^5.0.0"
-         }
-       }
-     }
  "require": {
-  "advanced-custom-fields/advanced-custom-fields-pro": "6.1.6",

But do not remove the alternative installer from allow-plugins yet,
as composer needs to have updated the dependencies once, before it can be removed without causing an error during deploy:

  "config": {
    "allow-plugins": {
      "ffraenz/private-composer-installer": true,

This line can be cleaned up after a successful deploy:

  "config": {
    "allow-plugins": {
-      "ffraenz/private-composer-installer": true,


ACF PRO Agency license (unlimited sites) / global fallback

  • The same authentication data as in auth.json has to be added to group_vars/<environment>/vault.yml:
+   # Advanced Custom Fields (ACF) PRO plugin
+  - {
+       hostname: "connect.advancedcustomfields.com",
+       username: "[ACF PRO license key]",
+       password: "https://[site host (must be non-empty and a full URL with protocol)]"
+    }

ACF PRO site-specific licenses

Set the password for each site host in vault_wordpress_sites (also in group_vars/<environment>/vault.yml):

+    composer_authentications:
+      - {
+           hostname: "connect.advancedcustomfields.com",
+           username: "[ACF PRO license key (to which this site belongs)]",
+           password: "https://example.com" # host of site
+        }
  • (Optional) Clean up old variables used with the previous installation method:
    But only clean this variable up when the affected site uses this new installation method.
- plugin_acf_key: "..."
  • Deploy the Bedrock site, the ACF PRO plugin should be installed by Trellis using this new method.

Possible issues and workarounds

  • composer caches the packages, hence failing authentication may not be apparent until the cache was invalidated.

Possible improvements and remarks

As the ACF PRO Agency license allows for unlimited sites, it could make sense to add the ACF PRO license globally and set a different password with the host for each site. However, interpolation of a global ACF PRO license variable does not work as these are not templates. As this will work just fine when setting just one site as password for all other sites, this may not be important.