建立的規格參考 CodeBuild - AWS CodeBuild
Buildspec 檔案名稱和儲存位置Buildspec 語法Buildspec 範例Buildspec 版本

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

建立的規格參考 CodeBuild

本主題提供關於建置規格 (Buildspec) 檔案的重要參考資訊。Buildspec 是建置命令和相關設定的集合 (YAML 格式)， CodeBuild 用來執行組建。您可以包含 buildspec 作為源代碼的一部分，也可以在創建構建項目時定義 buildspec。如需組建規格運作方式的詳細資訊，請參閱CodeBuild 運作方式。

主題

Buildspec 檔案名稱和儲存位置

若您隨著來源碼併入組建規格，依預設，組建規格檔案的名稱會是 buildspec.yml，並且放置在來源目錄的根目錄中。

您可以覆寫預設的組建規格檔案名稱和位置。例如，您可以：

  • 對相同儲存庫中的不同組建使用不同的組建規格檔案，例如 buildspec_debug.yml 和 buildspec_release.yml。

  • 在來源目錄根目錄以外的位置儲存組建規格檔案，例如 config/buildspec.yml，或儲存在 S3 儲存貯體中。S3 儲存貯體必須與您的建置專案位於相同的 AWS 區域。使用其 ARN 指定 buildspec 檔案 (例如，arn:aws:s3:::<my-codebuild-sample2>/buildspec.yml)。

您只可以為組建專案指定一個組建規格，而不論組建規格檔案的名稱。

若要覆寫預設的組建規格檔案名稱、位置或兩者，請執行下列其中一個動作：

  • 執行 AWS CLI create-project或update-project命令，將buildspec值設定為替代 buildspec 檔案的路徑，相對於內建環境變數的值。CODEBUILD_SRC_DIR您也可以對 AWS SDK 中的create project操作進行等效操作。如需詳細資訊，請參閱 建立組建專案 或 變更建置專案的設定 。

  • 執行 AWS CLI start-build指令，將buildspecOverride值設定為替代 buildspec 檔案的路徑，相對於內建環境變數的值。CODEBUILD_SRC_DIR您也可以對 AWS SDK 中的start build操作進行等效操作。如需詳細資訊，請參閱 執行建置。

  • 在 AWS CloudFormation 範本中，將資源類型Source中的BuildSpec屬性設定AWS::CodeBuild::Project為替代 buildspec 檔案的路徑 (相對於內建環境變數的值)。CODEBUILD_SRC_DIR若要取得更多資訊，請參閱《AWS CloudFormation 使用指南》中的AWS CodeBuild 專案來源中的 BuildSpec性質。

Buildspec 語法

組建規格檔案必須以 YAML 格式表達。

如果命令包含 YAML 不支援的字元或字元字串，您必須以引號 (“”) 括住命令。下列命令用引號括起來，因為 YAML 中不允許冒號 (:) 後面跟著空格。命令中的引號被逸出 (\")。

"export PACKAGE_NAME=$(cat package.json | grep name | head -1 | awk -F: '{ print $2 }' | sed 's/[\",]//g')"

組建規格具有下列語法：

version: 0.2

run-as: Linux-user-name

env:
  shell: shell-tag
  variables:
    key: "value"
    key: "value"
  parameter-store:
    key: "value"
    key: "value"
  exported-variables:
    - variable
    - variable
  secrets-manager:
    key: secret-id:json-key:version-stage:version-id
  git-credential-helper: no | yes

proxy:
  upload-artifacts: no | yes
  logs: no | yes

batch:
  fast-fail: false | true
  # build-list:
  # build-matrix:
  # build-graph:
        
phases:
  install:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    runtime-versions:
      runtime: version
      runtime: version
    commands:
      - command
      - command
    finally:
      - command
      - command
    # steps:
  pre_build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    commands:
      - command
      - command
    finally:
      - command
      - command
    # steps:
  build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    commands:
      - command
      - command
    finally:
      - command
      - command
    # steps:
  post_build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    commands:
      - command
      - command
    finally:
      - command
      - command
    # steps:
reports:
  report-group-name-or-arn:
    files:
      - location
      - location
    base-directory: location
    discard-paths: no | yes
    file-format: report-format
artifacts:
  files:
    - location
    - location
  name: artifact-name
  discard-paths: no | yes
  base-directory: location
  exclude-paths: excluded paths
  enable-symlinks: no | yes
  s3-prefix: prefix
  secondary-artifacts:
    artifactIdentifier:
      files:
        - location
        - location
      name: secondary-artifact-name
      discard-paths: no | yes
      base-directory: location
    artifactIdentifier:
      files:
        - location
        - location
      discard-paths: no | yes
      base-directory: location
cache:
  paths:
    - path
    - path

建置規格包含下列各項：

version

必要的映射。代表組建規格版本。建議您使用 0.2。

注意

雖然仍支援版本 0.1，建議您盡可能使用版本 0.2。如需詳細資訊，請參閱 Buildspec 版本。

執行方式

選用的序列。僅供 Linux 使用者使用。指定在此組建規格檔案中執行指令的 Linux 使用者。 run-as授與指定的使用者讀取和執行權限。在 buildspec 檔案上方指定 run-as 時，它會全域套用到所有命令。如果您不想為所有 buildspec 檔案命令指定一個使用者，您可以在其中一個 phases 區塊中使用 run-as 來為階段中的命令指定一個使用者。如果未指定 run-as，則會以根使用者身分執行所有命令。

env

選用的序列。代表一或多個自訂環境變數的資訊。

注意

為了保護敏感資訊，記 CodeBuild 錄檔中會隱藏下列項目：

外殼/殼

選用的序列。指定 Linux 或視窗作業系統支援的殼層。

對於 Linux 作業系統，支援的殼層標籤為：

  • bash

  • /bin/sh

對於 Windows 作業系統，支援的殼層標籤為：

  • powershell.exe

  • cmd.exe

env/variables

如果指定 env，且您想要以純文字定義自訂環境變數，則為必要。包含 key/value 純量的映射，其中的每個映射代表純文字的單一自訂環境變數。key 為自訂環境變數的名稱，而 value 為該變數的值。

重要

我們強烈建議在環境變量中存儲敏感值。環境變數可以使用 CodeBuild 主控台和 AWS CLI. 針對機密值，建議您改為使用 parameter-store 或 secrets-manager 映射，如本節稍後所述。

任何您設定的環境變數都會取代現有環境變數。例如，如果 Docker 影像已包含名為 MY_VAR 且值為 my_value 的環境變數，而且您設定名為 MY_VAR 且值為 other_value 的環境變數，則 my_value 會取代為 other_value。同樣地，如果 Docker 影像已包含名為 PATH 且值為 /usr/local/sbin:/usr/local/bin 的環境變數，而且您設定名為 PATH 且值為 $PATH:/usr/share/ant/bin 的環境變數，則 /usr/local/sbin:/usr/local/bin 會取代為文字值 $PATH:/usr/share/ant/bin。

請不要設定名稱開頭為 CODEBUILD_ 的任何環境變數。此字首保留供 內部使用。

如果有多個位置定義同名的環境變數，則會決定值，如下所示：

env/parameter-store

如果env已指定，且您想要擷取存放在 Amazon EC2 Systems Manager 參數存放區中的自訂環境變數，則需要此選項。包含鍵/值標量的對應，其中每個映射代表存放在 Amazon EC2 Systems Manager 參數存放區中的單一自訂環境變數。 key 是您稍後在建置命令中用來參照此自訂環境變數的名稱，而 value 是儲存在 Amazon EC2 Systems Manager 參數存放區中的自訂環境變數名稱。若要存放機密值，請參閱 Amazon EC2 Systems Manager 使用者指南中的系統管理員參數存放區和逐步解說：建立和測試字串參數 (主控台)。

重要

若 CodeBuild 要允許擷取存放在 Amazon EC2 Systems Manager 參數存放區中的自訂環境變數，您必須將ssm:GetParameters動作新增至 CodeBuild 服務角色。如需詳細資訊，請參閱 建立 CodeBuild 服務角色。

您從 Amazon EC2 Systems Manager 參數存放區擷取的任何環境變數都會取代現有的環境變數。例如，如果 Docker 影像已包含名為 MY_VAR 且值為 my_value 的環境變數，而且您擷取名為 MY_VAR 且值為 other_value 的環境變數，則 my_value 會取代為 other_value。同樣地，如果 Docker 影像已包含名為 PATH 且值為 /usr/local/sbin:/usr/local/bin 的環境變數，而且您擷取名為 PATH 且值為 $PATH:/usr/share/ant/bin 的環境變數，則 /usr/local/sbin:/usr/local/bin 會取代為文字值 $PATH:/usr/share/ant/bin。

請不要存放名稱開頭為 CODEBUILD_ 的任何環境變數。此字首保留供 內部使用。

如果有多個位置定義同名的環境變數，則會決定值，如下所示：

env/secrets-manager

如果您要擷取儲存在中的自訂環境變數，則為必要項目 AWS Secrets Manager。reference-key使用下列病毒碼指定密碼管理員：

<key>: <secret-id>:<json-key>:<version-stage>:<version-id>

<key>

(必要) 本機環境變數名稱。使用此名稱可在建置期間存取變數。

<secret-id>

(必要) 作為密碼唯一識別碼的名稱或 Amazon 資源名稱 (ARN)。若要存取您 AWS 帳戶中的秘密，只需要指定秘密名稱。若要存取不同 AWS 帳戶中的密碼，請指定秘密 ARN。

<json-key>

(選擇性) 指定您要擷取其值之 Secrets Manager 金鑰值配對的金鑰名稱。如果未指定json-key， CodeBuild 會擷取整個密碼文字。

<version-stage>

(選擇性) 指定您要透過附加至版本的暫存標籤擷取的密碼版本。預備標籤在輪換程序期間用來追蹤不同版本。如果您使用 version-stage，請不要指定 version-id。如果您不指定版本階段或版本 ID，則預設會擷取版本階段值為 AWSCURRENT 的版本。

<version-id>

(選擇性) 指定您要使用之密碼版本的唯一識別碼。如果指定 version-id，則不要指定 version-stage。如果您不指定版本階段或版本 ID，則預設會擷取版本階段值為 AWSCURRENT 的版本。

在下列範例中，TestSecret是儲存在 Secrets Manager 中的索引鍵值配對名稱。的關鍵TestSecret是MY_SECRET_VAR。您可以在建置期間使用LOCAL_SECRET_VAR名稱存取變數。

env:
  secrets-manager:
    LOCAL_SECRET_VAR: "TestSecret:MY_SECRET_VAR"

如需詳細資訊，請參閱 AWS Secrets Manager 使用者指南中的什麼是 AWS Secrets Manager。

env/exported-variables

選用的映射。用於列出您想要匯出的環境變數。在 exported-variables 下以獨立行列指定您想要匯出的每個變數的名稱。建置期間您想要匯出的變數必須在容器中提供。您匯出的變數可為環境變數。

匯出的環境變數可與搭配使用， AWS CodePipeline 將環境變數從目前的建置階段匯出至管線中的後續階段。若要取得更多資訊，請參閱《使用指南》中的〈AWS CodePipeline 使用變數〉。

建置期間，變數的值在 install 階段即開始提供。它可以在install 階段開始和 post_build 結束之間進行更新。post_build 階段結束後，匯出的變數值無法變更。

注意

無法匯出下列項目：

  • 建置專案中指定的 Amazon EC2 Systems Manager 參數存放區機密。

  • 建置專案中指定的密碼 Secrets Manager 密碼

  • 以 AWS_ 開頭的環境變數。

環/git-credential-helper

選用的映射。用於指示是否 CodeBuild 使用其 Git 憑證助手來提供 Git 憑據。 yes如果使用它。否則為 no 或未指定。如需詳細資訊，請參閱 Git 網站上的 gitcredentials。

注意

由公有 Git 儲存庫的 Webhook 觸發的建置不支援 git-credential-helper。

proxy

選用的序列。如果在明確的代理伺服器中執行建置，則用於表示設定。如需詳細資訊，請參閱 在明確代理伺服器中執行 CodeBuild。

proxy/upload-artifacts

選用的映射。如果您想要在明確的代理伺服器中的建置上傳成品，請設為 yes。預設值為 no。

proxy/logs

選用的映射。在明確的 Proxy 伺服器中，yes針對您的組建設定為，以建立 CloudWatch 記錄檔。預設值為 no。

階段

必要的序列。表示在構建的每個階段 CodeBuild 運行的命令。

注意

在 buildspec 版本 0.1 中， CodeBuild 在構建環境中的默認 shell 的單獨實例中運行每個命令。這表示每個命令會與所有其他命令隔離執行。因此，根據預設，如果單一命令倚賴任何之前命令的狀態 (例如，變更目錄或設定環境變數)，您就無法加以執行。為因應這個限制，我們建議您使用 0.2 版，它可解決這個問題。如果您必須使用組建規格版本 0.1，我們建議使用建置環境中的 Shell 和命令中的方法。

phases/*/run-as

選用的序列。在建置階段中用來指定可執行其命令的 Linux 使用者。如果也在 buildspec 檔案上方為所有命令全域指定 run-as，則階段層級的使用者具有優先權。例如，如果全局run-as指定了用戶 1，並且對於install階段只有一個run-as語句指定了用戶 2，那麼 buildspec 文件中的所有命令都將作為 User 1 運行，除了在install階段中運行的命令，這是作為用戶 2 運行。

階段 /*/ 失敗

選用的序列。指定在階段期間發生失敗時要採取的動作。這可以是下列其中一個值：

  • ABORT-中止構建。

  • CONTINUE-繼續下一階段。

如果未指定此屬性，失敗流程會遵循轉移階段，如中所示建置階段轉換。

階段 /*/ 最後

選用的區塊。圖塊中指定的指令會在finally圖塊中的commands指令之後執行。即使finally區塊中的指令失敗，區commands塊中的指令也會執行。例如，如果commands圖塊包含三個指令，而第一個指令失敗，則 CodeBuild 略過剩餘的兩個指令並執行finally圖塊中的任何指令。當 commands 和 finally 區塊中的所有命令成功執行時，此階段即成功。如果階段中的任何命令失敗，階段即失敗。

允許的建置階段名稱為：

phases/install

選用的序列。代表在安裝期間 CodeBuild 執行的指令 (如果有的話)。建議您僅針對在組建環境中安裝套件使用 install 階段。例如，您可能會使用此階段來安裝程式碼測試架構，例如 Mocha 或 RSpec。

phases/install/runtime-versions

選用的序列。Ubuntu 標準映像 5.0 或更新版本和 Amazon Linux 2 標準映像 4.0 或更新版本支援執行階段版本。如已指定，此區段中至少要包含一個執行時間。使用特定版本指定執行階段，主要版本後跟著指定 CodeBuild使用該主要版本及其最新次latest要版本，或使用最新的主要和次要版本 (例如ruby: 3.2nodejs: 18.x、、或java: latest)。.x您可以使用數字或環境變數指定執行時間。例如，如果您使用 Amazon Linux 2 標準映像檔 4.0，則以下內容指定安裝 Java 版本 17、Python 版本 3 的最新次要版本，以及包含在 Ruby 環境變數中的版本。如需詳細資訊，請參閱 碼頭圖片提供 CodeBuild。

phases:
  install:
    runtime-versions:
      java: corretto8
      python: 3.x
      ruby: "$MY_RUBY_VAR"

您可以在 buildspec 檔案的 runtime-versions 區段中指定一或多個執行時間。如果您的執行階段依存於另一個執行時間，您也可以在 buildspec 檔案中指定其相依的執行時間。如果您未在 buildspec 檔案中指定任何執行階段，請 CodeBuild 選擇您使用的映像中可用的預設執行階段。如果您指定一或多個執行階段，則只 CodeBuild 會使用這些執行階段。如果未指定相依執行階段，會 CodeBuild 嘗試為您選擇相依的執行階段。

如果兩個指定的執行時間發生衝突，則建置會失敗。例如，android: 29 和 java: openjdk11 相衝突，所以如果指定這兩個，則組建會失敗。

如需可用執行階段的詳細資訊，請參閱可用的執行階段。

注意

如果您指定runtime-versions區段並使用 Ubuntu 標準映像 2.0 或更新版本以外的映像檔，或 Amazon Linux 2 (AL2) 標準映像 1.0 或更新版本，則組建會發出警告「Skipping install of runtimes. Runtime version selection is not supported by this build image.」

phases/install/commands

選用的序列。包含一系列純量，其中每個純量代表在安裝期間 CodeBuild 執行的單一命令。 CodeBuild 依列出的順序從開始到結束執行每個指令，一次執行一個指令。

phases/pre_build

選用的序列。表示在構建之前 CodeBuild 運行的命令（如果有的話）。例如，您可以使用此階段登入 Amazon ECR，或者您可以安裝 npm 相依性。

phases/pre_build/commands

只有在指定 pre_build 時才為必要序列。包含一系列純量，其中每個純量代表在構建之前 CodeBuild 運行的單個命令。 CodeBuild依列出的順序從開始到結束執行每個指令，一次執行一個指令。

phases/build

選用的序列。代表建置期間 CodeBuild 執行的指令 (如果有的話)。例如，您可能會使用此階段來執行 Mocha、RSpec 或 sbt。

phases/build/commands

如果build已指定，則為必要。包含純量序列，其中每個純量代表在構建期間 CodeBuild 運行的單個命令。 CodeBuild 依列出的順序從開始到結束執行每個指令，一次執行一個指令。

phases/post_build

選用的序列。表示在構建後 CodeBuild 運行的命令（如果有的話）。例如，您可以使用 Maven 將構建成品打包到 JAR 或 WAR 文件中，或者您可以將 Docker 映像推送到 Amazon ECR 中。然後，您可以透過 Amazon SNS 傳送建置通知。

phases/post_build/commands

如果post_build已指定，則為必要。包含一系列純量，其中每個純量代表在構建後 CodeBuild運行的單個命令。 CodeBuild 依列出的順序從開始到結束執行每個指令，一次執行一個指令。

報告

report-group-name-or-arn

選用的序列。指定傳送報告的目標報告群組。一個專案最多可以擁有五個報告群組。指定現有報告群組的 ARN，或新報告群組的名稱。如果您指定名稱，請使用您的專案名稱和您在格式中指定的名稱來 CodeBuild 建立報表群組<project-name>-<report-group-name>。您也可以使用 buildspec 中的環境變數來設定報表群組名稱，例如。$REPORT_GROUP_NAME如需詳細資訊，請參閱 報告群組命名。

reports/<report-group>/files

必要的序列。代表包含由建立產生之測試結果原始資料的位置。包含一系列純量，每個標量代表一個單獨的位置，其中 CodeBuild 可以找到測試文件，相對於原始構建位置或（如果設置）。base-directory位置可能包括下列：

  • 單一檔案 (例如，my-test-report-file.json)。

  • 子目錄中的單一檔案 (例如，my-subdirectory/my-test-report-file.json 或 my-parent-subdirectory/my-subdirectory/my-test-report-file.json)。

  • '**/*' 代表遞迴的所有檔案。

  • my-subdirectory/* 代表名為 my-subdirectory 的子目錄中的所有檔案。

  • my-subdirectory/**/* 代表從名為 my-subdirectory 開始的子目錄遞迴的所有檔案。

reports/<report-group>/file-format

選用的映射。代表報表檔案格式。如果未指定，則會使用 JUNITXML。此值不區分大小寫。可能值為：

測試報告
CUCUMBERJSON

Cucumber JSON

JUNITXML

JUnit XML

NUNITXML

NUnit XML

NUNIT3XML

單位 3

TESTNGXML

TestNG XML

VISUALSTUDIOTRX

Visual Studio TRX

代碼覆蓋率報告
CLOVERXML

三叶草

COBERTURAXML

XML 編輯器

JACOCOXML

JaCoCo XML

SIMPLECOV

SimpleCov JSON

注意

CodeBuild 接受簡單生成的 JSON 代碼覆蓋報告，而不是簡單的 JSON 代碼覆蓋率。

reports/<report-group>/base-directory

選用的映射。代表相對於原始構建位置的一個或多個頂級目錄， CodeBuild 用於確定在哪裡找到原始測試文件。

reports/<report-group>/discard-paths

選用。指定報告檔案目錄是否在輸出中平面化。如果未指定或包含 no，則報告檔案會以完整的目錄結構輸出。如果包含 yes，則所有的測試檔案都會放置在相同的輸出目錄中。例如，如果測試結果的路徑是 com/myapp/mytests/TestResult.xml，則指定 yes 會將此檔案置於 /TestResult.xml 中。

工藝品

選用的序列。代表在何處 CodeBuild 可以找到組建輸出，以及如何 CodeBuild 準備上傳至 S3 輸出儲存貯體的資訊。例如，如果您正在建立 Docker 映像並將其推送到 Amazon ECR，或者您正在對原始程式碼執行單元測試，但未建置它，則不需要此序列。

注意

Amazon S3 中繼資料有一個名為的 CodeBuild 標頭，x-amz-meta-codebuild-buildarn其buildArn中包含將成品發佈到 Amazon S3 的 CodeBuild 組建。buildArn已新增以允許來源追蹤通知，以及參考從中產生成品的組建。

artifacts/files

必要的序列。代表包含組建環境中組建輸出成品的位置。包含純量的序列，每個純量代表不同的位置， CodeBuild 可以在該位置找到建置輸出成品 (相對於原始建置位置，或如果有設定的話，則為基本目錄)。位置可能包括下列：

  • 單一檔案 (例如，my-file.jar)。

  • 子目錄中的單一檔案 (例如，my-subdirectory/my-file.jar 或 my-parent-subdirectory/my-subdirectory/my-file.jar)。

  • '**/*' 代表遞迴的所有檔案。

  • my-subdirectory/* 代表名為 my-subdirectory 的子目錄中的所有檔案。

  • my-subdirectory/**/* 代表從名為 my-subdirectory 開始的子目錄遞迴的所有檔案。

當您指定組建輸出加工品位置時， CodeBuild 可以在建置環境中尋找原始建置位置。您不需要在組建成品輸出位置前方附加原始組建位置的路徑或指定 ./ 之類內容。如果要知道此位置的路徑，您可以在組建期間執行 echo $CODEBUILD_SRC_DIR 之類命令。每個組建環境的位置可能稍有不同。

artifacts/name

選用名稱。指定組建成品的名稱。當下列其中一項成立時，會使用此名稱。

  • 您可以使用 CodeBuild API 建立組建，並在更新專案、建立專案或啟動組建時，在ProjectArtifacts物件上設定overrideArtifactName旗標。

  • 您可以使用 CodeBuild 控制台來創建構建，在 buildspec 文件中指定名稱，並在創建或更新項目時選擇啟用語義版本控制。如需詳細資訊，請參閱 建立組建專案 (主控台)。

您可以在組建時計算的組建規格檔案中指定名稱。組建規格檔案中指定的名稱使用 Shell 命令語言。例如，您可以將日期和時間附加到成品名稱，讓它一律是唯一的。唯一成品名稱可防止覆寫成品。如需詳細資訊，請參閱 Shell 命令語言。

  • 這是成品名稱附加了成品建立日期的範例。

    version: 0.2
phases:
  build:
    commands:
      - rspec HelloWorld_spec.rb
artifacts:
  files:
    - '**/*'
  name: myname-$(date +%Y-%m-%d)

  • 這是使用 CodeBuild 環境變數的成品名稱範例。如需詳細資訊，請參閱 建置環境中的環境變數。

    version: 0.2
phases:
  build:
    commands:
      - rspec HelloWorld_spec.rb
artifacts:
  files:
    - '**/*'
  name: myname-$AWS_REGION

  • 這是一個人工因素名稱的範例，它使用 CodeBuild 環境變數並附加了人工因素的建立日期。

    version: 0.2
phases:
  build:
    commands:
      - rspec HelloWorld_spec.rb
artifacts:
  files:
    - '**/*'
  name: $AWS_REGION-$(date +%Y-%m-%d)

您可以將路徑資訊新增至名稱，以便根據名稱中的路徑將具名的人工因素放置在目錄中。在此範例中，組建加工品會放置在下的輸出中builds/<build number>/my-artifacts。

version: 0.2
phases:
  build:
    commands:
      - rspec HelloWorld_spec.rb
artifacts:
  files:
    - '**/*'
  name: builds/$CODEBUILD_BUILD_NUMBER/my-artifacts
artifacts/discard-paths

選用。指定組建成品目錄是否在輸出中平面化。如果未指定或包含 no，則會以完整的目錄結構輸出組建成品。如果包含 yes，則所有組建成品都會放置在相同的輸出目錄中。例如，如果組建輸出成品中的文件路徑是 com/mycompany/app/HelloWorld.java，則會指定 yes 將此文件放置在 /HelloWorld.java 中。

artifacts/base-directory

選用的映射。代表相對於原始組建位置的一或多個頂層目錄， CodeBuild 用來決定組建輸出加工品中要包含哪些檔案和子目錄。有效值包含：

  • 單一上層目錄 (例如，my-directory)。

  • 'my-directory*' 代表名稱開頭為 my-directory 的所有上層目錄。

相符的上層目錄不會包含在組建輸出成品中，只有其檔案和子目錄。

您可以使用 files 和 discard-paths 以進一步限制包含的檔案和子目錄。例如，針對下列目錄結構：

.
├── my-build-1
│   └── my-file-1.txt
└── my-build-2
    ├── my-file-2.txt
    └── my-subdirectory
        └── my-file-3.txt

以及下列 artifacts 序列：

artifacts:
  files:
    - '*/my-file-3.txt'
  base-directory: my-build-2

下列子目錄和檔案會包含在組建輸出成品中：

.
└── my-subdirectory
    └── my-file-3.txt

當下列 artifacts 序列：

artifacts:
  files:
    - '**/*'
  base-directory: 'my-build*'
  discard-paths: yes

下列檔案會包含在組建輸出成品中：

.
├── my-file-1.txt
├── my-file-2.txt
└── my-file-3.txt
人工品/排除路徑

選用的映射。代表一個或多個相對於， CodeBuild 將從組建加工品中排除的路徑。base-directory星號 (*) 字元符合不超過資料夾邊界之名稱元件的零個或多個字元。雙星號 (**) 會在所有目錄中比對名稱元件的零個或多個字元。

排除路徑的範例包括：

  • 若要從所有目錄中排除檔案："**/file-name/**/*"

  • 若要排除所有點資料夾："**/.*/**/*"

  • 若要排除所有點檔案："**/.*"

選用。如果輸出類型為ZIP，則指定是否在 ZIP 檔案中保留內部符號連結。如果包含yes，則來源中的所有內部符號連結都會保留在成品 ZIP 檔案中。

人工/S3 前綴

選用。指定當成品輸出到 Amazon S3 儲存貯體且命名空間類型為時使用的前置詞BUILD_ID。使用時，值區中的輸出路徑為<s3-prefix>/<build-id>/<name>.zip。

artifacts/secondary-artifacts

選用的序列。代表一或多個成品定義，做為成品識別符與成品定義之間的映射。此區塊中的每個成品識別符必須符合專案的 secondaryArtifacts 屬性中定義的成品。每個個別的定義具有與以上 artifacts 區塊相同的語法。

注意

即使只有定義次要加工品，此artifacts/files序列始終是必要的。

例如，如果您的專案具有以下結構：

{
  "name": "sample-project",
  "secondaryArtifacts": [
    {
      "type": "S3",
      "location": "<output-bucket1>",
      "artifactIdentifier": "artifact1",
      "name": "secondary-artifact-name-1"
    },
    {
      "type": "S3",
      "location": "<output-bucket2>",
      "artifactIdentifier": "artifact2",
      "name": "secondary-artifact-name-2"
    }
  ]
}

則您的 buildspec 如下所示：

version: 0.2

phases:
build:
  commands:
    - echo Building...
artifacts:
  files:
    - '**/*'
  secondary-artifacts:
    artifact1:
      files:
        - directory/file1
      name: secondary-artifact-name-1
    artifact2:
      files:
        - directory/file2
      name: secondary-artifact-name-2

快取

選用的序列。代表 CodeBuild 可在何處準備檔案以將快取上傳至 S3 快取儲存貯體的相關資訊。如果專案的快取類型為 No Cache，則此序列不是必要。

cache/paths

必要的序列。代表快取的位置。包含一系列純量，每個純量代表一個單獨的位置，其中 CodeBuild 可以找到構建輸出加工品，相對於原始構建位置或基本目錄（如果設置）。位置可能包括下列：

  • 單一檔案 (例如，my-file.jar)。

  • 子目錄中的單一檔案 (例如，my-subdirectory/my-file.jar 或 my-parent-subdirectory/my-subdirectory/my-file.jar)。

  • '**/*' 代表遞迴的所有檔案。

  • my-subdirectory/* 代表名為 my-subdirectory 的子目錄中的所有檔案。

  • my-subdirectory/**/* 代表從名為 my-subdirectory 開始的子目錄遞迴的所有檔案。

重要

因為建置規格宣告必須為有效的 YAML，因此建置規格宣告中的間距相當重要。若您組建規格宣告中的空格數無效，組建會立即失敗。您可以使用 YAML 驗證程式來測試您的組建規格宣告是否為有效的 YAML。

如果您在建立或更新建置專案時使用或 AWS SDK 來宣告 Buildspec，則組建規格必須是以 YAML 格式表示的單一字串，以及必要的空白和換行符逸出字元。 AWS CLI下一節提供一個範例。

如果您使用 CodeBuild 或 AWS CodePipeline 控制台而不是 buildspec.yml 檔案，則只能插入階段的命令。build不要使用前述語法，您應該在單一行中列出要在組建階段期間執行的所有命令。針對多個命令，以 && 區隔每個命令 (例如，mvn test && mvn package)。

您可以使用 CodeBuild 或 CodePipeline 控制台而不是 buildspec.yml 文件來指定構建環境中構建輸出成品的位置。不要使用前述語法，而是應該在單一行中列出所有位置。針對多個位置，以逗號區隔每個位置 (例如，buildspec.yml, target/my-app.jar)。

Buildspec 範例

以下是 buildspec.yml 檔案的範例。

version: 0.2

env:
  variables:
    JAVA_HOME: "/usr/lib/jvm/java-8-openjdk-amd64"
  parameter-store:
    LOGIN_PASSWORD: /CodeBuild/dockerLoginPassword

phases:
  install:
    commands:
      - echo Entered the install phase...
      - apt-get update -y
      - apt-get install -y maven
    finally:
      - echo This always runs even if the update or install command fails 
  pre_build:
    commands:
      - echo Entered the pre_build phase...
      - docker login -u User -p $LOGIN_PASSWORD
    finally:
      - echo This always runs even if the login command fails 
  build:
    commands:
      - echo Entered the build phase...
      - echo Build started on `date`
      - mvn install
    finally:
      - echo This always runs even if the install command fails
  post_build:
    commands:
      - echo Entered the post_build phase...
      - echo Build completed on `date`

reports:
  arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1:
    files:
      - "**/*"
    base-directory: 'target/tests/reports'
    discard-paths: no
  reportGroupCucumberJson:
    files:
      - 'cucumber/target/cucumber-tests.xml'
    discard-paths: yes
    file-format: CUCUMBERJSON # default is JUNITXML
artifacts:
  files:
    - target/messageUtil-1.0.jar
  discard-paths: yes
  secondary-artifacts:
    artifact1:
      files:
        - target/artifact-1.0.jar
      discard-paths: yes
    artifact2:
      files:
        - target/artifact-2.0.jar
      discard-paths: yes
cache:
  paths:
    - '/root/.m2/**/*'

以下是前述 buildspec 的範例，以單一字串表示，以與 AWS CLI、或 SDK 搭配使用。 AWS 

"version: 0.2\n\nenv:\n  variables:\n    JAVA_HOME: \"/usr/lib/jvm/java-8-openjdk-amd64\\"\n  parameter-store:\n    LOGIN_PASSWORD: /CodeBuild/dockerLoginPassword\n  phases:\n\n  install:\n    commands:\n      - echo Entered the install phase...\n      - apt-get update -y\n      - apt-get install -y maven\n    finally:\n      - echo This always runs even if the update or install command fails \n  pre_build:\n    commands:\n      - echo Entered the pre_build phase...\n      - docker login -u User -p $LOGIN_PASSWORD\n    finally:\n      - echo This always runs even if the login command fails \n  build:\n    commands:\n      - echo Entered the build phase...\n      - echo Build started on `date`\n      - mvn install\n    finally:\n      - echo This always runs even if the install command fails\n  post_build:\n    commands:\n      - echo Entered the post_build phase...\n      - echo Build completed on `date`\n\n reports:\n  reportGroupJunitXml:\n    files:\n      - \"**/*\"\n    base-directory: 'target/tests/reports'\n    discard-paths: false\n  reportGroupCucumberJson:\n    files:\n      - 'cucumber/target/cucumber-tests.xml'\n    file-format: CUCUMBERJSON\n\nartifacts:\n  files:\n    - target/messageUtil-1.0.jar\n  discard-paths: yes\n  secondary-artifacts:\n    artifact1:\n      files:\n       - target/messageUtil-1.0.jar\n      discard-paths: yes\n    artifact2:\n      files:\n       - target/messageUtil-1.0.jar\n      discard-paths: yes\n cache:\n  paths:\n    - '/root/.m2/**/*'"

以下是build階段中指令的範例，可與 CodeBuild 或 CodePipeline 主控台搭配使用。

echo Build started on `date` && mvn install

在這些範例中：

  • 純文字的自訂環境變數，已設定 JAVA_HOME 的金鑰和 /usr/lib/jvm/java-8-openjdk-amd64 的值。

  • 稍後會在建置命令中使用金鑰參數存放區參考dockerLoginPassword您儲存在 Amazon EC2 Systems Manager 參數存放區中的自訂環境變數LOGIN_PASSWORD。

  • 您無法變更這些組建階段名稱。在此範例中執行的命令是apt-get update -y和 apt-get install -y maven (安裝 Apache Maven)、mvn install (編譯、測試和封裝原始程式碼至建置輸出成品，並在其內部儲存庫中安裝建置輸出成品)、docker login (使用與dockerLoginPassword您在 Amazon EC2 Systems Manager 參數存放區中設定的自訂環境變數值對應的密碼登入 Docker) 以及數個echo命令。這裡包含這些echo指令，以顯示 CodeBuild 執行命令的方式以及執行命令的順序。

  • files 代表要上傳至組建輸出位置的檔案。在此範例中， CodeBuild 上傳單一檔案messageUtil-1.0.jar。您可以在組建環境中名為 target 的相對目錄中找到 messageUtil-1.0.jar 檔案。因為已指定 discard-paths: yes，系統會直接上傳 messageUtil-1.0.jar (並且不會上傳到中繼 target 目錄)。檔案名稱 (messageUtil-1.0.jar) 及相對目錄名稱 (target) 是以 Apache Maven 建立及存放組建輸出成品的方式為基礎，僅適用於此範例。在您自己的案例中，檔案名稱及目錄可能會有所不同。

  • reports 代表在建置期間產生報告的兩個報告群組：

    • arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1 指定報告群組的 ARN。以測試框架產生的測試結果位於 target/tests/reports 目錄。檔案格式為 JunitXml，且路徑不會從包含測試結果的檔案移除。

    • reportGroupCucumberJson 指定新的報告群組。如果專案的名稱為 my-project，則會在組件執行時會建立名稱為 my-project-reportGroupCucumberJson 的報告群組。以測試框架產生的測試結果位於 cucumber/target/cucumber-tests.xml。測試檔案格式為 CucumberJson，且路徑不會從包含測試結果的檔案移除。

Buildspec 版本

下表列出組建規格版本與版本之間的變更。

版本 變更
0.2

  • environment_variables 已重新命名為 env。

  • plaintext 已重新命名為 variables。

  • 已捨棄 artifacts 的 type 屬性。

  • 在版本 0.1 中， AWS CodeBuild 在構建環境中的默認 shell 的單獨實例中運行每個構建命令。在 0.2 版中， CodeBuild 在構建環境中的默認 shell 的相同實例中運行所有構建命令。
0.1 這是組建規格格式的初始定義。