Git repository requirements¶

When creating your external Git repository, ensure the repository contains the following items:

• One or more branches or tags.
• One or more sets of Drupal theme files to use with your website. Place each theme’s file in a separate directory, named with the theme’s name.

Cloud Platform requires deployment keys be associated with a user account. As GitHub does not support the use of the same deployment key for multiple repositories, create a Cloud Platform user as described in Deployment keys and Cloud Platform. Associate the key with a user account, instead of adding the SSH key as a deployment key.

Creating a theme repository allowlist¶

To protect hosted websites from using themes containing potentially harmful settings or code, you can add a allowlist file of approved theme repositories to Site Factory. When administrative users try to add a theme repository, Site Factory compares the repository with the contents of the acsf_theme_allowlist.txt file.

To create an allowlist file for your theme repositories:

1. Create a file to contain your allowlist settings, based on the following conventions:
   • Enter each external Git repository on a separate line.
   • You can add comments to entries by starting lines with the number sign ( # ). The # isn’t used for allowlist filtering.
   • Use the asterisk character ( * ) for wildcard entry.
   • If you don’t end a repository line with an asterisk, its use is implied.
2. Save the file with the name acsf_theme_allowlist.txt in the root directory of your code repository.
3. Commit your code changes with the new allowlist file to your codebase.
4. Deploy the code to your production environment.

# Allow any github repos from the Acquia organization
github.com:acquia/*

# Allow specific github repo
github.com:SU-SWS/open_framework

# Allow the Zen theme from Drupal.org
git.drupal.org:project/zen.git

Connecting to a theme repository¶

To connect to an external Git repository containing one or more themes:

1. Sign in to the Site Factory Management Console as a user with either the Platform admin or Site builder role.
2. Find the website you want to modify, open its actions menu, and then click Manage theme repository.
3. Click Connect site repository to enter your Git repository’s information.
4. Click the Show SSH public key link to display the SSH public key.
5. Select and copy the contents of the SSH public key field to your clipboard.
6. Open a new browser tab and sign in to your Git repository.
7. Add the SSH public key to the theme repository, and configure the key to have read access.
8. Open a new browser tab and sign in to the Acquia user account.
9. Add the SSH public key to the user account.

10. Return to the page in which you are entering your theme repository information, and then enter the following values for the Git repository you want to use:

    • Git URL: The Git SSH URL of the theme repository (for example, [email protected]:repo.git)
    • Branch or tag: A valid branch or tag from the theme repository

    Note

    To ensure that the theme changes for one website do not affect other websites that use the same theme, Acquia recommends you to use discrete tags for all environments. However, it is worth noting that using branches for staged websites can speed your theme development process.

11. Click Save.

Site Factory compares theme repositories to entries in the allowlist file based on the following parameters:

• The user@ preceding the theme repository is ignored.
• Theme repositories beginning with an exact match of one or more of the allowlist file entries are accepted. For example, a allowlist entry of github.com would match [email protected]:repo.git.

If the allowlist file blocks a theme repository, Site Factory will display an error message and keep the previous theme repository settings.

If no error messages display, your Git repository themes will be checked out for use by your website. After the checkout completes, you can view the themes by signing in to the website and clicking Appearance in the admin menu.

Refreshing your theme¶

Whenever you make changes to your theme files, and commit those changes to the Git theme repository, you must update your websites’ theme files based on the correct branch or tag. You must update every website using the updated theme.

To refresh your theme on a single website:

1. If you are refreshing a theme for a stack running the current Drupal version stack, create a post-theme-deploy hook script, as described in Performing custom actions after theme deployments, to clear the Twig cache after you deploy the updated theme.
2. Sign in to the Site Factory Management Console using an account with either the Platform admin or Site builder role.
3. Find the website you want to modify, open its actions menu, and then click Manage theme repository.
4. Select the appropriate method based on whether you are using a branch (staged websites) or a tag (production websites):
   • Branch: Click Refresh themes.
   • Tag –
     1. Click the Change site theme repository link.
     2. In the Branch or tag list, click the tag with the new theme changes.
     3. Click Save.

Site Factory obtains your new theme changes from the Git repository and adds them to your website. After it makes copies of the theme files, the theme changes display in the website’s Appearance page (and if the theme is in use, on the website itself).

#!/bin/bash
drush8 @$1.$2 --uri=$5 ev '\Drupal\Core\PhpStorage\PhpStorageFactory::get("twig")->deleteAll();'

More information¶

• Hooks in Site Factory
• The Send a theme notification endpoint in the Site Factory API
• The Process theme modifications endpoint in the Site Factory API