工作流程问题疑难解答 - Amazon CodeCatalyst

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

工作流程问题疑难解答

要解决与 Amazon 工作流程相关的问题,请参阅以下章节 CodeCatalyst。有关工作流的更多信息,请参阅使用中的工作流程构建、测试和部署 CodeCatalyst

如何修复 “工作流程处于非活动状态” 消息?

问题:在 CodeCatalyst 控制台的 C I/CD工作流程” 下,您的工作流程将显示以下消息:

Workflow is inactive.

此消息表示工作流程定义文件包含不适用于您当前所在分支的触发器。例如,您的工作流程定义文件可能包含引用您的main分支的PUSH触发器,但您位于功能分支上。由于您在功能分支中所做的更改不适用于也不会启动工作流程在中运行main,因此在该分支 CodeCatalyst 上停用工作流程并将其标记为Inactivemain

可能的修复措施:

如果要在功能分支上启动工作流程,可以执行以下操作:

  • 在您的功能分支中,在工作流程定义文件中,从该Triggers部分中移除该Branches属性,使其如下所示:

    Triggers: - Type: PUSH

    此配置会使触发器在推送到任何分支(包括您的功能分支)时激活。如果激活了触发器,则 CodeCatalyst 将使用工作流程定义文件和你要推送到的任何分支中的源文件启动工作流程运行。

  • 在您的功能分支中,在工作流程定义文件中,删除该Triggers部分并手动运行工作流程。

  • 在您的功能分支中,在工作流程定义文件中,更改该PUSH部分,使其引用您的功能分支而不是另一个分支(例如main)。

重要

如果您不打算将这些更改合并回main分支,请注意不要提交这些更改。

有关编辑工作流程定义文件的更多信息,请参阅创建工作流

有关触发器的更多信息,请参阅使用触发器自动启动工作流程

如何修复 “工作流定义有 n 个错误” 错误?

问题:您会看到以下任何错误消息:

错误 1:

在 C I/CD 的 “工作流程” 页面中,在您的工作流程名称下,您会看到:

Workflow definition has n errors

错误 2:

编辑工作流程时,选择 “验证” 按钮, CodeCatalyst 控制台顶部会显示以下消息:

The workflow definition has errors. Fix the errors and choose Validate to verify your changes.

错误 3:

导航到工作流程的详细信息页面后,您会在工作流程定义字段中看到以下错误:

n errors

可能的修复措施:

  • 选择 CI/CD,选择 Workflows,然后选择出现错误的工作流程的名称。在靠近顶部的 “工作流程定义” 字段中,选择错误链接。有关错误的详细信息显示在页面底部。按照错误中的疑难解答提示修复问题。

  • 确保工作流程定义文件是 YAML 文件。

  • 确保工作流定义文件中的 YAML 属性嵌套在正确的级别。要了解应如何将属性嵌套在工作流程定义文件中,请参阅或查阅您的操作文档,该文档已链接至 from 向 CodeCatalyst 工作流程添加操作工作流程 YAML 定义

  • 确保正确转义星号 (*) 和其他特殊字符。要避开它们,请添加单引号或双引号。例如:

    Outputs: Artifacts: - Name: myartifact Files: - "**/*"

    有关工作流程定义文件中特殊字符的更多信息,请参见语法指南和惯例

  • 确保工作流程定义文件中的 YAML 属性使用正确的大小写。有关大小写规则的更多信息,请参阅语法指南和惯例。要确定每个属性的正确大小写,请参阅或查阅您的操作文档,该文档链接至 from 向 CodeCatalyst 工作流程添加操作工作流程 YAML 定义

  • 确保该SchemaVersion属性存在并在工作流程定义文件中设置为正确的版本。有关更多信息,请参阅 SchemaVersion

  • 确保工作流程定义文件中的Triggers部分包含所有必需的属性。要确定所需的属性,请在可视化编辑器中选择触发器并查找缺少信息的字段,或者参阅触发器参考文档,网址为Triggers

  • 确保工作流定义文件中的DependsOn属性配置正确,并且不会引入循环依赖关系。有关更多信息,请参阅 将操作配置为依赖于其他操作

  • 确保工作流程定义文件中的Actions部分至少包含一个操作。有关更多信息,请参阅 操作

  • 确保每个操作都包含所有必需的属性。要确定所需的属性,请在可视化编辑器中选择操作并查找缺少信息的字段,或者查阅操作的文档,该文档的链接来自于向 CodeCatalyst 工作流程添加操作

  • 确保所有输入工件都有相应的输出伪影。有关更多信息,请参阅 定义输出对象

  • 确保导出在一个操作中定义的变量,以便可以在其他操作中使用它们。有关更多信息,请参阅 导出变量以便其他操作可以使用它

如何修复 “找不到凭证” 和 “ExpiredToken” 错误?

问题:在完成操作时教程:将应用程序部署到 Amazon EKS,你会在开发计算机的终端窗口中看到以下一条或两条错误消息:

Unable to locate credentials. You can configure credentials by running "aws configure".

ExpiredToken: The security token included in the request is expired

可能的修复措施:

这些错误表明您用于访问 AWS 服务的凭证已过期。在这种情况下,请不要运行该aws configure命令。相反,请按照以下说明刷新您的 AWS 访问密钥和会话令牌。

刷新您的 AWS 访问密钥和会话令牌
  1. 请确保您拥有正在使用的用户的 AWS 访问门户 URL、用户名和密码,完成了 Amazon EKS 教程 (codecatalyst-eks-user)。完成本教程后,您应该已经配置第 1 步:设置开发机器了这些项目。

    注意

    如果您没有这些信息,请前往 IAM Identity Center 的codecatalyst-eks-user详细信息页面,选择重置密码生成一次性密码 [...] ,然后再次重置密码以在屏幕上显示信息。

  2. 请执行以下操作之一:

    • 将 AWS 访问门户 URL 粘贴到浏览器的地址栏中。

      Or

    • 如果 AWS 访问门户页面已加载,请刷新该页面。

  3. 如果您尚未登录,请使用codecatalyst-eks-user的用户名和密码登录。

  4. 选择 AWS 账户,然后选择 AWS 账户 向其分配codecatalyst-eks-user用户和权限集的名称。

  5. 在权限集名称 (codecatalyst-eks-permission-set) 旁边,选择命令行或编程访问权限

  6. 复制页面中间的命令。它们看起来类似于以下内容:

    export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE" export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" export AWS_SESSION_TOKEN="session-token"

    ... 其中 session-token 是一个长随机字符串。

  7. 将命令粘贴到开发计算机上的终端提示符中,然后按 Enter。

    新密钥和会话令牌已加载。

    现在,您已经刷新了凭证。 AWS CLIeksctl、和kubectl命令现在应该可以正常工作了。

如何修复 “无法连接到服务器” 错误?

问题:在学习中描述的教程时教程:将应用程序部署到 Amazon EKS,你会在开发计算机的终端窗口中看到一条类似于以下内容的错误消息:

Unable to connect to the server: dial tcp: lookup long-string.gr7.us-west-2.eks.amazonaws.com on 1.2.3.4:5: no such host

可能的修复措施:

此错误通常表示该kubectl实用程序用于连接您的 Amazon EKS 集群的证书已过期。要解决此问题,请在终端提示符下输入以下命令来刷新凭据:

aws eks update-kubeconfig --name codecatalyst-eks-cluster --region us-west-2

其中:

  • codecatalyst-eks-cluster将替换为您的 Amazon EKS 集群的名称。

  • us-west-2 被替换为部署集群 AWS 的区域。

为什么可视化编辑器中缺少 CodeDeploy 字段?

问题:您正在使用 “部署到 Amazon ECS” 操作,但在工作流程的可视化编辑器CodeDeploy AppSpec中看不到诸如此类的 CodeDeploy 字段。之所以出现此问题,是因为您在 “服务” 字段中指定的 Amazon ECS 服务未配置为执行蓝/绿部署。

可能的修复措施:

如何修复 IAM 功能错误?

问题:您正在使用部署 AWS CloudFormation 堆栈操作,并且可以在部署 AWS CloudFormation 堆栈操作的日志##[error] requires capabilities: [capability-name]中看到。

可能的修复方法:完成以下步骤,将该功能添加到工作流程定义文件中。有关 IAM 功能的更多信息,请参阅 IAM 用户指南中的在 AWS CloudFormation 模板中确认 IAM 资源

Visual
使用可视化编辑器添加 IAM 功能
  1. 打开 CodeCatalyst 控制台,网址为 https://codecatalyst.aws/

  2. 选择您的项目。

  3. 在导航窗格中,选择 C I/CD,然后选择工作流程。

  4. 选择工作流程的名称。您可以按定义工作流程的源存储库或分支名称进行筛选,也可以按工作流程名称进行筛选。

  5. 选择编辑

  6. 选择 “视觉”。

  7. 在工作流程图中,选择您的部署 AWS CloudFormation 堆栈操作。

  8. 选择配置选项卡。

  9. 在底部,选择高级-可选

  10. 功能下拉列表中,选中错误消息中提及的功能旁边的复选框。如果列表中没有该功能,请使用 YAML 编辑器添加该功能。

  11. (可选)选择 “验证” 以在提交之前验证工作流程的 YAML 代码。

  12. 选择 “提交”,输入提交消息,然后再次选择 “提交”。

  13. 如果新的工作流程运行未自动启动,请手动运行工作流程以查看更改是否修复了错误。有关手动运行工作流程的更多信息,请参阅启动工作流程手动运行

YAML
使用 YAML 编辑器添加 IAM 功能
  1. 打开 CodeCatalyst 控制台,网址为 https://codecatalyst.aws/

  2. 选择您的项目。

  3. 在导航窗格中,选择 C I/CD,然后选择工作流程。

  4. 选择工作流程的名称。您可以按定义工作流程的源存储库或分支名称进行筛选,也可以按工作流程名称进行筛选。

  5. 选择编辑

  6. 选择 YAML。

  7. 在 “部署 AWS CloudFormation 堆栈” 操作中,添加一个capabilities属性,如下所示:

    DeployCloudFormationStack: Configuration: capabilities: capability-name

    capability-name 替换为错误消息中显示的 IAM 功能的名称。使用逗号和空格列出多项功能。有关更多信息,请参阅中对capabilities属性的描述“部署 AWS CloudFormation 堆栈” 操作 YAML 定义

  8. (可选)选择 “验证” 以在提交之前验证工作流程的 YAML 代码。

  9. 选择 “提交”,输入提交消息,然后再次选择 “提交”。

  10. 如果新的工作流程运行未自动启动,请手动运行工作流程以查看更改是否修复了错误。有关手动运行工作流程的更多信息,请参阅启动工作流程手动运行

如何修复 “npm 安装” 错误?

问题:您的AWS CDK 部署操作AWS CDK 引导操作npm install错误而失败。之所以发生此错误,可能是因为您将 AWS CDK 应用程序依赖项存储在操作无法访问的私有节点包管理器 (npm) 注册表中。

可能的修复方法:按照以下说明使用其他注册表和身份验证信息更新 AWS CDK 应用程序的cdk.json文件。

开始前的准备工作
  1. 为您的身份验证信息创建密钥。你将在cdk.json文件中引用这些秘密,而不是提供等效的明文信息。要创建机密,请执行以下操作:

    1. 打开 CodeCatalyst 控制台,网址为 https://codecatalyst.aws/

    2. 选择您的项目。

    3. 在导航窗格中,选择 C I/CD,然后选择密钥。

    4. 使用以下属性创建两个密钥:

      第一个秘密 第二个秘密

      名称npmUsername

      npm-usern ame,其中 npm-usernam e 是用于向私有 npm 注册表进行身份验证的用户名。

      (可选)描述The username used to authenticate to the private npm registry.

      名称npmAuthToken

      :npm-auth-token,其中npm-auth-token是用于向您的私有 npm 注册表进行身份验证的访问令牌。有关 npm 访问令牌的更多信息,请参阅 npm 文档中的关于访问令牌

      (可选)描述The access token used to authenticate to the private npm registry.

      有关密钥的更多信息,请参阅在工作流程中配置和使用密钥

  2. 将密钥作为环境变量添加到您的 AWS CDK 操作中。该操作将在运行时用实数值替换变量。要添加秘密,请执行以下操作:

    1. 在导航窗格中,选择 C I/CD,然后选择工作流程。

    2. 选择工作流程的名称。您可以按定义工作流程的源存储库或分支名称进行筛选,也可以按工作流程名称进行筛选。

    3. 选择编辑

    4. 选择 “视觉”。

    5. 在工作流程图中,选择您的 AWS CDK 操作。

    6. 选择输入选项卡。

    7. 添加两个具有以下属性的变量:

      第一个变量 第二个变量

      名称NPMUSER

      ${Secrets.npmUsername}

      名称NPMTOKEN

      ${Secrets.npmAuthToken}

      现在,你有两个包含对机密的引用的变量。

    您的工作流程定义文件 YAML 代码应类似于以下内容:

    注意

    以下代码示例来自AWS CDK 引导操作;AWS CDK 部署操作将与之类似。

    Name: CDK_Bootstrap_Action SchemaVersion: 1.0 Actions: CDKBootstrapAction: Identifier: aws/cdk-bootstrap@v1 Inputs: Variables: - Name: NPMUSER Value: ${Secrets.npmUsername} - Name: NPMTOKEN Value: ${Secrets.npmAuthToken} Sources: - WorkflowSource Environment: Name: Dev2 Connections: - Name: account-connection Role: codecatalystAdmin Configuration: Parameters: Region: "us-east-2"

    现在,您已准备好在cdk.json文件中使用NPMUSERNPMTOKEN变量了。继续下一过程。

更新你的 cdk.json 文件
  1. 切换到 AWS CDK 项目的根目录,然后打开该cdk.json文件。

  2. 找到该"app":属性,然后将其更改为包含以红色斜体显示的代码:

    注意

    以下示例代码来自一个 TypeScript 项目。如果您使用的是 JavaScript 项目,则代码看起来很相似,但并不相同。

    { "app": "npm set registry=https://your-registry/folder/CDK-package/ --userconfig .npmrc && npm set //your-registry/folder/CDK-package/:always-auth=true --userconfig .npmrc && npm set //your-registry/folder/CDK-package/:_authToken=\"${NPMUSER}\":\"${NPMTOKEN}\" && npm install && npx ts-node --prefer-ts-exts bin/hello-cdk.ts|js", "watch": { "include": [ "**" ], "exclude": [ "README.md", "cdk*.json", "**/*.d.ts", "**/*.js", "tsconfig.json", "package*.json", ...
  3. 在以红色斜体突出显示的代码中,替换:

    • y@@ our-registry/Folder/CDK-package/,其中包含私有注册表中项目依赖项的路径。 AWS CDK

    • hello-cdk.ts|.js,上面写着你的入口点文件的名字。这可能是 .ts (TypeScript) 或 .js (JavaScript) 文件,具体取决于你使用的语言。

      注意

      该操作将使用你在 Secrets 中指定的 npm 用户名和访问令牌替换 NPM USER 和 NPMTOKEN 变量。

  4. 保存 cdk.json 文件。

  5. 手动重新运行该操作以查看更改是否修复了错误。有关手动运行操作的更多信息,请参阅启动工作流程手动运行

为什么多个工作流程同名?

工作流程存储在每个存储库的每个分支上。如果两个不同的工作流程存在于不同的分支中,则它们可以具有相同的名称。在 “工作流程” 页面中,您可以通过查看分支名称来区分同名工作流程。有关更多信息,请参阅 使用 Amazon 中的分支来整理源代码 CodeCatalyst

工作流程分支

我能否将我的工作流程定义文件存储在另一个文件夹中?

不,您必须将所有工作流程定义文件存储在.codecatalyst/workflows文件夹中。如果您使用的是包含多个逻辑项目的 mono 存储库,请将所有工作流程定义文件放在该.codecatalyst/workflows文件夹中,然后使用 Trigger 中的FilesChanged属性在指定的项目路径上触发工作流程。有关更多信息,请参阅 使用触发器自动启动工作流程

如何按顺序向我的工作流程添加操作?

默认情况下,当你向工作流程中添加操作时,它将没有依赖关系,将与其他操作并行运行。

如果要按顺序排列动作,则可以通过设置DependsOn字段来设置对另一个动作的依赖关系。您也可以将操作配置为使用作为其他操作输出的构件或变量。有关更多信息,请参阅 将操作配置为依赖于其他操作

为什么我的工作流程成功验证但在运行时失败?

如果您使用Validate按钮验证了工作流程,但无论如何您的工作流程都失败了,则可能是因为验证器存在限制。

在提交过程中,在工作流程配置中引用密钥、环境或队列等 CodeCatalyst 资源时出现的任何错误都不会被记录下来。如果使用了任何无效的引用,则只有在运行工作流程时才会发现错误。同样,如果操作配置中存在任何错误,例如缺少必填字段或操作属性中有错别字,则只有在工作流程运行时才会识别出来。有关更多信息,请参阅 创建工作流

自动发现不会发现任何与我的操作相关的报告

问题:我为运行测试的操作配置了自动发现,但未发现任何报告。 CodeCatalyst

可能的修复方法:这可能是由许多问题引起的。尝试以下一种或多种解决方案:

  • 确保用于运行测试的工具以一种可以 CodeCatalyst 理解的格式生成输出。例如,如果您想pytest CodeCatalyst 允许发现测试和代码覆盖率报告,请包含以下参数:

    --junitxml=test_results.xml --cov-report xml:test_coverage.xml

    有关更多信息,请参阅 质量报告类型

  • 确保输出的文件扩展名与所选格式一致。例如,在配置为pytestJUnitXML格式生成结果时,请检查文件扩展名是否为.xml。有关更多信息,请参阅 质量报告类型

  • 确保将其配置IncludePaths为包括整个文件系统 (**/*),除非您故意排除某些文件夹。同样,请确保ExcludePaths不要排除您期望报告所在的目录。

  • 如果您手动将报告配置为使用特定的输出文件,则该报告将被排除在自动发现之外。有关更多信息,请参阅 质量报告 YAML 示例

  • 自动发现可能找不到报告,因为操作在生成任何输出之前就失败了。例如,构建可能在运行任何单元测试之前就失败了。

配置成功标准后,我对自动发现的报告执行操作失败

问题:当我启用自动发现并配置成功标准时,有些报告不符合成功标准,因此操作失败。

可能的修复方法:要解决此问题,请尝试以下一种或多种解决方案:

  • ExcludePaths修改IncludePaths或排除您不感兴趣的报告。

  • 更新成功标准以允许所有报告通过。例如,如果发现两个报告,其中一个的线路覆盖率为 50%,另一个报告为 70%,则将最小线覆盖率调整为 50%。有关更多信息,请参阅成功标准

  • 将失败的报告转换为手动配置的报告。这允许您为该特定报告配置不同的成功标准。有关更多信息,请参阅 为报告配置成功标准

自动发现会生成我不想要的报告

问题:当我启用自动发现功能时,它会生成我不想要的报告。例如,为存储在我的应用程序依赖项中的文件 CodeCatalyst 生成代码覆盖率报告node_modules

可能的修复方法:您可以调整ExcludePaths配置以排除不需要的文件。例如,要排除node_modules,请添加node_modules/**/*。有关更多信息,请参阅 包含/排除路径

自动发现为单个测试框架生成许多小报告

问题:当我使用某些测试和代码覆盖率报告框架时,我注意到自动发现会生成大量报告。例如,在使用 Maven Surefire 插件时,自动发现会为每个测试类生成不同的报告。

可能的修复:您的框架可能能够将输出聚合到单个文件中。例如,如果您使用的是 Maven Surefire 插件,则可以使用npx junit-merge手动聚合文件。完整的表达式可能如下所示:

mvn test; cd test-package-path/surefire-reports && npx junit-merge -d ./ && rm *Test.xml

CI/CD 下列出的工作流程与源存储库中的工作流程不匹配

问题:C I/CD、Workflows 页面上显示的工作流程存储库中~/.codecatalyst/workflows/文件夹中的工作流程不匹配。您可能会看到以下不匹配项:

  • 工作流程显示在 “工作流程” 页面上,但源存储库中不存在相应的工作流程定义文件。

  • 您的源存储库中存在工作流程定义文件,但相应的工作流程未显示在 “工作流程” 页面上。

  • 源存储库和工作流页面中都存在工作流程,但两者不同。

如果工作流程页面没有时间刷新,或者超过了工作流程配额,则可能会出现此问题。

可能的修复措施:

  • 等待。提交源代码后,通常需要等待两三秒钟才能在 “工作流程” 页面上看到更改。

  • 如果您已超过工作流程配额,请执行以下任一操作:

    注意

    要确定是否已超过工作流程配额,请根据源存储库或工作流程页面上的工作流程查看工作流程配额并交叉检查记录的配额。没有错误消息表明已超出配额,因此您必须自己进行调查。

    • 如果您已超过每个空间的最大工作流程数量配额,请删除一些工作流程,然后对工作流程定义文件执行测试提交。测试提交的一个例子可能是向文件添加一个空格。

    • 如果您已超过最大工作流程定义文件大小配额,请更改工作流程定义文件以缩短其长度。

    • 如果您已超过在单个源事件中处理的最大工作流程文件数量配额,请执行多次测试提交。修改的工作流程数量少于每次提交的最大数量。

    • 通过开启付费等级计费来增加工作流程配额。有关更多信息,请参阅《Amazon CodeCatalyst 管理员指南》中的管理账单

我无法创建或更新工作流程

问题:我想创建或更新工作流程,但是当我尝试提交更改时出现错误。

可能的修复方法:根据您在项目或空间中的角色,您可能无权将代码推送到项目中的源存储库。工作流程的 YAML 文件存储在存储库中。有关更多信息,请参阅 工作流程定义文件Space 管理员角色、项目管理员角色和参与者角色均有权提交代码并将其推送到项目中的仓库。

如果您具有贡献者角色,但无法在特定分支中创建或提交对工作流程 YAML 的更改,则可能为该分支配置了分支规则,该规则禁止具有该角色的用户将代码推送到该特定分支。尝试在不同的分支中创建工作流程,或者将您的更改提交到其他分支。有关更多信息,请参阅 使用分支规则管理分支允许的操作