README

此Composer包提供测试和部署托管站点的起点。

升级
依赖项
安装
配置环境
配置CircleCI config.yml
- 管道参数默认值
  - php-version
  - tz
  - host-variant
    - pantheon
    - acquia
    - general
  - docroot
  - artifact_workspace
- 其他配置
  - persisting_dirs
可配置环境变量
辅助环境变量
配置composer.json
配置脚本
- Pantheon特定脚本
自动安全更新
- 设置密钥的步骤
- 设置IA密钥的步骤

升级

如果您使用的是此包中提供的标准脚本，升级应该会更加容易。每次版本升级时，您都应该检查您的.circleci/config.yml文件，以查看与这里的config.yml文件有什么变化。

这样做最简单的方法是使用标准化的diff工具，并将.circleci/config.yml与config.yml进行diff。一个例子可能如下所示

diff -u --color .circleci/config.yml ./vendor/fourkitchens/pots/config.yml

验证更改，并将您想保留的更改移动过来。

依赖项

此包假定您的项目具有以下支持脚手架，以便能够直接运行

composer脚本lint和代码嗅探。示例

 "scripts": {
    "lint": [
       "./node_modules/.bin/eslint ./",
       "find web/modules/custom web/themes/custom \\( -iname  '*.php' -o -iname '*.inc' -o -iname '*.module' -o -iname '*.install'-o -iname '*.theme' \\) '!' -path '*/node_modules/*' -print0 | xargs -0 -n1 -P8 php -l"
    ],
    "code-sniff": [
       "./vendor/bin/phpcs"
    ]
 }

包含构建主题脚本的package.json。示例

   "scripts": {
      "theme-build": "cd ./docroot/themes/custom/sdsu && npm run build"
   }

package.lock或shrinkwrap。
最好有一个.nvmrc文件
带有删除行的.gitignore文件，以区分源和工件。以下是一个示例 .gitignore。

Circle任务设置假定您正在使用机器人用户进行此操作。请确保您使用的机器人用户在您的网站所在的GitHub组织和托管提供商上都有账户。您将需要

以机器人用户身份登录GitHub和托管提供商的能力
SSH密钥（私钥和公钥）
托管工具（如Terminus或acli）的API或机器令牌

安装

安装包并复制模板config.yml

composer require fourkitchens/pots
mkdir .circleci
cp vendor/fourkitchens/pots/config.yml .circleci/config.yml

确保您的composer.json和package.json符合默认脚本的要求数
将更改推送到公共GitHub分支。
登录到 https://app.circleci.com/
通过点击左上角您的名字处的图标并选择正确的选项，导航到您的网站代码所在的组织。
导航到项目
找到您的网站名称
点击它旁边的“设置项目”按钮
选择“最快”
在对话框中输入您推送到其中的更改的分支，其中“git branch”图标位于其中。
验证扳手图标变成绿色，并通知您已找到 config.json 文件。
点击“设置项目”。

第一次运行总是会失败。请继续进行配置。

配置环境

某些配置步骤在托管环境中是通用的。请确保检查您要推送到的环境的特定设置。

共享

部署机器人设置

需要一个 Deploy Bot 用户。此工具假定 Bender（Four Kitchens 的部署 Bot）为默认值，但不提供设置此工具所需的任何凭证。向 Web Chef 询问 Bender，让合作的组织创建一个新的 Bot，或按照以下步骤为他们创建新的 Bot。您需要以该 Bot 的身份登录来完成一些配置。

为部署机器人创建GitHub账户

打开一个新的浏览器实例或从当前的 GitHub 实例注销。
访问 https://github.com/join。
输入用户名、您的电子邮件地址和密码。注意：确保您输入的电子邮件地址是真实的电子邮件账户。如果您使用 Gmail，则可以使用电子邮件中的 + 将多个“地址”发送到同一个账户。请参阅如何创建特定任务电子邮件地址
选择“在 GitHub 上注册”，然后按照说明进行操作。
安全地向客户提供凭证。
在新浏览器实例中，作为拥有网站的组织的管理员，邀请 Bot 用户加入组织。

配置SSH密钥

需要一个 SSH 密钥才能从 circleci 推送提交到托管提供商的 git 仓库。在某些情况下，相同的 SSH 密钥还需要用于连接到托管平台本身。要求客户生成 SSH 密钥对或生成并安全地向客户提供 SSH 密钥对。

登录到 https://app.circleci.com/
通过点击左上角您的名字处的图标并选择正确的选项，导航到您的网站代码所在的组织。
导航到项目
找到您网站的存储库名称并点击它。
验证您是否看到了失败的工怍流。
点击“项目设置”。
点击“SSH 密钥”。
导航到“其他 SSH 密钥”。
点击“添加 SSH 密钥”。
将提供给 Bot 用户的私钥内容复制到出现的对话框中的“私钥”字段。
验证您没有多余的空格或换行符。
点击“添加 SSH 密钥”以关闭对话框并接受更改。
注意指纹以供将来使用。注意：您可以通过验证 circleci 中的指纹是否与命令 ssh-keygen -l -E md5 -f id_rsa（其中 idrsa 是您的密钥文件名）显示的内容相同，来检查文件是否已正确复制。

获取Github令牌

您需要一个 GitHub 令牌，以便 Deploy Bot 能够在提交或拉取请求上发布评论。这允许它提供有关创建的环境的链接和信息。

如果您跳到了这里，请确保您遵循“配置 SSH 密钥”中的步骤 1-6，以进入 Circle 的项目设置。

在新浏览器实例中，以 Deploy Bot 的身份登录到 GitHub。
遵循创建个人访问令牌的说明。
选择“完整存储库访问”选项。
安全地保存访问令牌，以便您可以访问它。它只会显示一次。

配置环境变量

在此，您将配置通用环境变量。特定的托管变量和步骤将在下面提供。要配置的变量如下。

GITHUB_TOKEN 一个 GitHub 访问令牌，以便 Bot 用户可以在提交上评论。
GIT_EMAIL 用于构建工件时的提交者所使用的任意电子邮件地址。
CANONICAL_ENV 获取规范数据库和文件的环境。

如果您跳到了这里，请确保您遵循“配置 SSH 密钥”中的步骤 1-6，以进入 Circle 的项目设置。

切换回您登录到 CircleCI 的浏览器实例 -> 项目设置
点击左侧的“环境变量”。
点击“添加环境变量”。
在名称中输入“GITHUB_TOKEN”。
将令牌值复制到“值”中。
点击“添加环境变量”以接受更改。
点击“添加环境变量”。
在名称中输入“GIT_EMAIL”。
将与 Deploy Bot 关联的电子邮件地址输入到“值”中。
点击“添加环境变量”以接受更改。

Pantheon

SITE_NAME：用于运行 terminus 命令的 Pantheon 网站ID。
TERMINUS_TOKEN：用于操作 terminus 的 Pantheon Machine 令牌。

为部署机器人创建Pantheon账户

对于 Pantheon 托管的网站，我们需要一个用于 Deploy Bot 的账户，以便我们的部署与任何 Pantheon 用户关联。

以 Pantheon 组织管理员身份登录。
点击仪表板右上角的您的用户名。
导航到您想创建用户的组织名称。
点击“人员”标签。
点击“添加用户”按钮。
选择“团队成员”作为角色。
添加之前为 GitHub 账户创建的同一电子邮件地址。
点击“添加用户”。
在新浏览器实例中检查与该用户关联的电子邮件。
接受邀请。

设置SSH密钥

您的机器人需要一个配置了 ssh 密钥，以便能够将提交推送到 Pantheon。使用“配置 SSH 密钥”部分中生成的密钥对的公钥。

从您的 Pantheon 账户登出或使用单独的浏览器实例，按照 Pantheon 的说明将 SSH 密钥添加到 Pantheon。

获取Terminus令牌（或机器令牌）

在上面的同一浏览器实例中，按照 Pantheon 的说明创建机器令牌
安全地保存机器令牌，以便您能够访问它。它只会显示一次。

配置更多CircleCi环境变量

导航回到 CircleCI -> 项目设置 -> 环境变量浏览器实例。
点击“添加环境变量”。
在名称中输入“SITE_NAME”。
将您的 Pantheon 网站ID（或 TERMINUS SITE ID）输入到“值”中。注意：您可以在 Pantheon 中的网站仪表板中找到网站ID。如果您点击任何环境的“访问网站”按钮，则 URL 的格式为 https://{{TERMINUS ENV}}-{{TERMINUS SITE}}.pantheonsite.io/
点击“添加环境变量”以接受更改。
点击“添加环境变量”。
在名称中输入“TERMINUS_TOKEN”。
将您之前保存的机器令牌值复制到“值”中。
点击“添加环境变量”以接受更改。

Acquia

SITE_NAME：用于运行 Acquia Cloud API 命令的 acquia 网站ID。
ACQUIA_REALM：Cloud API Realm。通常是“prod”或“devcloud”。
ACQUIA_REPO：Acquia git 仓库。

为部署机器人创建Acquia账户

TODO：填写此部分

设置SSH密钥

您的机器人需要一个配置了 ssh 密钥，以便能够将提交推送到 Acquia。使用“配置 SSH 密钥”部分中生成的密钥对的公钥。

从您的 Acquia 账户登出或使用单独的浏览器实例，按照 Acquia 的说明将公钥添加到 Acquia 个人资料。

配置更多CircleCi环境变量

导航回到 CircleCI -> 项目设置 -> 环境变量浏览器实例。
点击“添加环境变量”。
在名称中输入“ACQUIA_REPO”。
将 Acquia 仓库 URL 输入到“值”中。TODO：更多帮助以获取它
点击“添加环境变量”以接受更改。
点击“添加环境变量”。
在名称中输入“ACQUIA_REALM”。
将 Acquia Realm ID 输入到“值”中。TODO：更多帮助以获取它
点击“添加环境变量”以接受更改。
点击“添加环境变量”。
在名称中输入“SITE_NAME”。
将 Acquia 网站ID复制到“值”中。TODO：更多帮助以获取它
点击“添加环境变量”以接受更改。
点击“添加环境变量”。
在名称中输入“ZD_REQUESTER_ID”。
将客户端请求者 ID 输入到“值”中。用户 ID 可以从用户的 URL 中获取。例如 https://advomatic.zendesk.com/agent/users/378771022972/requested_tickets
点击“添加环境变量”以接受更改。
点击“添加环境变量”。
在名称中输入“ZD_TOKEN”。
将Zendesk令牌值id输入到“值”中。此令牌存储在1password中。
点击“添加环境变量”以接受更改。
点击“添加环境变量”。
在名称中输入“ZD_LEAD_EMAIL”。
将项目负责人电子邮件值id输入到“值”中。项目的负责人电子邮件。
点击“添加环境变量”以接受更改。

配置CircleCI config.yml

您有许多选项可以选择，有些是共享的，有些是特定于宿主机的。

管道参数默认值

目前，您可以通过设置一些管道参数默认值来配置整个脚本。这些可以通过API调用（高级用法）进行更改，但当您直接向存储您的.circleci/config.yml仓库提交拉取请求或提交时，将使用默认值。

在每个参数中，更改default:键后面的值。例如，要更改整个项目的docroot，将

  docroot:
    description: "Where composer installs drupal."
    default: "web"
    type: string

更改为

  docroot:
    description: "Where composer installs drupal."
    default: "docroot" #NOTE I CHANGED THIS
    type: string

以下参数存在

php-version

这是一个表示整个构建中使用的PHP版本的版本号字符串。

如果您使用Pantheon作为宿主变体，则只能使用主要.minor版本号，例如"8.1"，因为Pantheon Docker容器只允许两位数字版本。

在其他宿主平台上，您可以使用三位数字版本号（major.minor.patch），例如在需要时使用"8.1.4"，但是允许使用两位数字。

tz

这是一个表示时区的字符串。这可能很重要，因为这样做可以确保进行时间计算的作业、打印时间戳或进行提交都是准确的。请查看时区值完整列表，以找到适合您使用的时区。

host-variant

这会影响整个构建的行为以及可用的配置。当前选项为“pantheon”、“acquia”和“general”。所有我们的工作流程都将为您提供“工件构建”，提交适当的仓库。这允许您使用Git历史记录将构建回溯到我们在开发中使用的源提交。

pantheon

Pantheon为您提供了一种构建多开发环境的流程，有关开发分支的选项，以及通过CircleCI用户界面进行代码部署的流程。此设置提供的部署过程使用Pantheon的Terminus和构建工具插件创建工件构建。这些更改仅提交到Pantheon git仓库，而不是您的“源仓库”，即您在其中创建编码更改的仓库。

acquia

Acquia提供了一种非常简单的流程，但是它确实在构建中提供了acquia cli。这允许您使用我们云钩子等支持部署方法来简化部署过程。对于多开发功能，建议使用tugboat。这些设置提供的部署过程使用一些标准的git命令创建工件构建。这些更改仅提交到Acquia git仓库，而不是您的“源仓库”，即您在其中创建编码更改的仓库。

general

“General”为您提供最简单的部署，将工件构建提交回您的源仓库下的新分支，该分支遵循deploy-{BRANCHNAME}命名约定。例如，如果您的分支名为test，您将有一个提交到deploy-test分支的工件构建。

docroot

此设置应设置为您的Drupal安装所在的文件夹。这应与extra.drupal-scaffold.locations.web-root中的设置相匹配。这通常是Pantheon的web或Acquia的docroot，但对于通用主机可以是任何数量的事物，如public_html。

artifact_workspace

此设置用于移动构建生成的工件的位置。当您想从构建中挑选项目，而不是将整个工件发送到宿主时，这个功能特别有用。《code>~/project目录始终提交到“工件构建”。因此，将此目录更改为类似《code>/tmp/project的路径，可以使用rsync将之前构建脚本构建的部分移动到《code>~/project。默认情况下，此设置的值为《code>~/project，因此“构建”作业期间构建的所有内容都将推送到宿主。

其他配置

有些配置无法通过API调用进行更改，您需要直接修改config.yml以暂时或永久更改它们。

persisting_dirs

这些目录是您希望从工作流的构建部分完整复制到部署部分的目录。有时，您可能还想包括像《code>node_modules、《code>simplesaml或《code>private这样的其他根目录。我们排除了大多数顶级目录，因为它们在托管系统本身中是不必要的。

可配置环境变量

可以使用CircleCI环境变量界面配置环境变量，或者您可以直接在《code>.circleci/config.yml中设置它们。在界面中更改它们可以使升级《code>.circleci/config.yml的问题减少，但这也隐藏了您可能正在使用的一些开关。根据最佳实践，请确保在CircleCI UI中配置任何密钥。我们也将所有必填环境变量以这种方式包括在内。

共享

GITHUB_TOKEN：必需一个GitHub访问令牌，以便机器人用户可以对提交或PR进行评论，并删除不需要的多devs。
SITE_NAME：用于运行terminus/acli命令的Pantheon或Acquia站点ID。默认为GitHub仓库名。
GIT_EMAIL：用于构建工件时的提交者的任意电子邮件。默认为《code>bender@fourkitchens.com
CANONICAL_ENV：获取规范数据库和文件的环境。可能的值
- Acquia：dev、test、prod
- Pantheon：dev、test、live
默认：Acquia上的“prod”。Pantheon上的“live”。
SANITIZE_SCRIPT：用于清理数据库的脚本。仅在《code>CANONICAL_ENV不是dev时使用。没有默认值。
SYNC_CONFIG：开启或关闭配置同步的能力。默认情况下，如果./config目录（包括）中的任何目录包含《code>system.site.yml，则为是。例如：如果《code>./config/system.site.yml或《code>./config/default/system.site.yml或《code>./config/sync/system.site.yml存在，则为是。可能的值是《code>YES或《code>NO。

Pantheon特定

TERMINUS_TOKEN：必需 Pantheon机器令牌。
CI_BUILD：在Pantheon上的每次提交时构建CI multidevs。这样您就可以得到ci-*环境。这可能在视觉回归测试或没有PR的工作流中很有用。默认为《code>NO。可能的值是《code>YES和《code>NO。
MAIN_BRANCH：定义从哪个主分支创建发布。如果存在分支，默认为《code>main，否则为《code>master。
DEVELOPMENT_BRANCH：定义GitHub上活跃开发发生的开发分支。在gitflow开发模式中使用最多。默认为《code>develop。
REBUILD_MULTIDEV_ENV_EVERY_PUSH：每次向Pantheon推送时，为multidevs重新同步内容。默认为《code>NO。可能的值是《code>YES和《code>NO。
REBUILD_DEVELOPMENT_ENV_EVERY_PUSH：每次向《code>DEVELOPMENT_BRANCH分支推送时，在Pantheon上重新同步GitHub开发multidev的内容。默认为《code>NO。可能的值是《code>YES和《code>NO。
DEVELOPMENT_ENV：定义用于GitHub开发分支的multidev的名称。必须遵循Pantheon的multidev命名约定。默认为《code>github-dev。

Acquia特定

ACQUIA_REPO：必需 Acquia git仓库的地址。例如：《code>sitename@svn-21939.prod.hosting.acquia.com:sitename.git。
ACQUIA_REALM：必需 Acquia Cloud API领域。通常是“prod”或“devcloud”。请参阅文档。默认为《code>prod。

辅助环境变量

这些环境变量不可配置。它们被设置为帮助您在自己的环境中开发脚本。其中一些包含先前提到的管道参数的值。

HOST_VARIANT：包含主机变体管道参数提供的值。
DATE_TIMEZONE：包含tz管道参数提供的值。
DOCROOT：包含docroot管道参数提供的值。
TERM："xterm"。

配置composer.json

有两个脚本，默认脚本要求您构建，以便在整个项目中可重用。您必须在项目中运行以下命令。

composer run lint
composer run code-sniff

有关示例，请参阅依赖关系部分。

配置脚本

此框架提供的几乎所有操作都可以进行重载。通过在.circleci/scripts的正确位置提供脚本，您可以让这个工具执行任何想要的步骤。我们在这个存储库的脚本部分提供了一组默认操作，您可以使用它来创建自定义脚本。

可重载的脚本如下

test/static：提供静态代码测试，如代码风格检查和代码标准验证。默认情况下，它运行composer run lint; composer run code-sniff
build/php：提供构建您应用程序的功能。默认情况下，这仅仅是优化一个生产就绪的依赖项安装。
build/theme：提供构建您自定义主题的功能。默认情况下，它运行npm run theme-build并遍历$DOCROOT/themes/custom，对每个.gitignore执行“剪切”操作，因此您可以在编码时提供应忽略的项目列表，并在构建工件时提供应忽略的项目列表。
deploy：将工件构建推送到远程托管环境的所有所需操作。在Pantheon上，这包括创建和构建multidev。在Acquia和通用托管上，这仅将工件代码推送到它应该存在的仓库。

Pantheon特定脚本

drush-commands：提供基本的部署drush命令以运行更新钩子、清除缓存和同步配置。
drush-config-import：提供导入配置的命令。默认情况下，它提供drupal 8+就绪的命令，如drush cim，但可以替换为类似于drush fra的命令，如果在drupal 7或基于功能的网站配置设置中。
post-drush-commands：一些站点需要对外部系统进行更改，例如solr、第三方缓存或希望运行drush deploy:hook以允许drush运行HOOK_deploy_NAME()作为某些后部署清理代码。请参阅Drush文档。
deploy-to-test：提供将更改部署到预发布环境的部署逻辑。默认情况下，它提供“部署”服务，同步实时到测试，并进行标准部署。
deploy-to-live：提供将更改部署到生产环境的部署逻辑。默认情况下，它提供备份服务、“部署”服务和标准部署。

自动安全更新。

POTS包含步骤和脚本，以自动查找安全更新并将它们安装到不同的贡献项目中。

这是通过使用CircleCI Pipeline参数来触发运行检查和获取安全更新的脚本的工作的CI作业构建的。

为了使其重新触发，我们有几个选项

Evercurrent（推荐）
CircleCi触发接口

为了使自动安全更新适用于我们的项目，我们将需要遵循以下步骤

创建一组新的SSH密钥，以便能够将更改推送到github（github部署密钥）
配置Zendesk集成（环境变量 - 已在上文文档化）
（可选）配置IA集成（Open IA）

设置密钥的步骤

当在一个项目上配置持续集成时，CircleCI会生成一组SSH密钥，并将私钥自动添加到CircleCI，公钥添加到GitHub。这样，CircleCI将能够访问GitHub上的仓库，但这种访问权限仅为只读。最初，对于POTS来说，这种访问权限已经足够，因为它只需要读取GitHub上的仓库并在托管网站的平台（Acquia、Pantheon、Platform等）上写入。

随着AutoSec的加入，这组SSH密钥就不再足够了，因为AutoSec需要读取仓库、执行安全更新并将更改发送到GitHub，因此从AutoSec开始，就需要有读写权限的密钥。CircleCI无法生成具有写入权限的密钥，因此需要在外部创建一组SSH密钥，并将其手动添加到CircleCI和GitHub。

密钥可以通过控制台中的命令通过此指南生成，或者也可以通过1password生成。
将私钥添加到CircleCI：项目设置 -> SSH密钥 -> 其他SSH密钥。
将公钥添加到GitHub：项目设置 -> 部署密钥。

设置IA密钥的步骤

AutoSec的开发是为了使用IA自动获取一些更新包的功能测试。这些步骤被添加到PR文档中，从而为执行测试的开发者提供重要信息。

AI实现是通过ChatGPT API完成的，因此需要生成并添加到CircleCI的一个密钥。重要的是要说明，使用此密钥的每个请求都有成本，因此配置此密钥是可选的，系统是为了检查是否存在密钥，它会向ChatGPT请求步骤，如果没有配置密钥，则不会进行任何请求。

生成新的API密钥，导航到OpenIA页面并登录，选择API控制台。
在左侧边栏中导航到“API密钥”（悬停在OpenIA标志上）。
点击“创建新的密钥”按钮并复制哈希代码。
将API密钥添加到CircleCI，导航：项目设置 -> SSH密钥 -> 环境变量。
点击“添加环境变量”按钮。
变量名必须是：OPENAI_API_KEY，值粘贴步骤3中的哈希代码。

fourkitchens / pots

维护者

详细信息

README

目录

升级

依赖项

安装

配置环境

共享

部署机器人设置

为部署机器人创建GitHub账户

配置SSH密钥

获取Github令牌

配置环境变量

Pantheon

为部署机器人创建Pantheon账户

设置SSH密钥

获取Terminus令牌（或机器令牌）

配置更多CircleCi环境变量

Acquia

为部署机器人创建Acquia账户

设置SSH密钥

配置更多CircleCi环境变量

配置CircleCI config.yml

管道参数默认值

php-version

tz

host-variant

pantheon

acquia

general

docroot

artifact_workspace

其他配置

persisting_dirs

可配置环境变量

共享

Pantheon特定

Acquia特定

辅助环境变量

配置composer.json

配置脚本

Pantheon特定脚本

自动安全更新。

设置密钥的步骤

设置IA密钥的步骤