程式碼 Build 的建置規格參考 - AWS CodeBuild

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

程式碼 Build 的建置規格參考

本主題提供關於建置規格 (Buildspec) 檔案的重要參考資訊。ABuildSpec是 CodeBuild 用來執行組建的一組組建命令與相關設定 (使用 YAML 格式)。您可以隨著來源碼併入組建規格,或也可以在建立組建專案時定義組建規格。如需組建規格運作方式的詳細資訊,請參閱程式 CodeBuild 的運作方式

Buildspec 檔案名稱和儲存位置

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

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

  • 對相同儲存庫中的不同組建使用不同的組建規格檔案,例如 buildspec_debug.ymlbuildspec_release.yml

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

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

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

  • 執行 AWS CLI create-projectupdate-project 命令,將 buildspec 的值設為替代組建規格檔案的路徑 (與內建環境變數 CODEBUILD_SRC_DIR 的值相對)。您也可以使用 AWS 軟體開發套件中的 create project 操作執行同等動作。如需詳細資訊,請參閱「建立組建專案」或「變更建置專案的設定」。

  • 執行 AWS CLI start-build 命令,將 buildspecOverride 的值設為替代組建規格檔案的路徑 (與內建環境變數 CODEBUILD_SRC_DIR 的值相對)。您也可以使用 AWS 軟體開發套件中的 start build 操作執行同等動作。如需更多詳細資訊,請參閱 執行建置

  • 在 AWS CloudFormation 範本中,將類型 AWS::CodeBuild::Project 之資源中 SourceBuildSpec 內容設為替代組建規格檔案的路徑 (與內建環境變數 CODEBUILD_SRC_DIR 的值相對)。如需詳細資訊,請參閱AWS CodeBuild專案來源中的AWS CloudFormation使用者指南

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 pre_build: run-as: Linux-user-name on-failure: ABORT | CONTINUE commands: - command - command finally: - command - command build: run-as: Linux-user-name on-failure: ABORT | CONTINUE commands: - command - command finally: - command - command post_build: run-as: Linux-user-name on-failure: ABORT | CONTINUE commands: - command - command finally: - command - command 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 使用者使用。指定會執行此 buildspec 檔案中命令的 Linux 使用者。run-as授與指定的使用者讀取和執行權限。在 buildspec 檔案上方指定 run-as 時,它會全域套用到所有命令。如果您不想為所有 buildspec 檔案命令指定一個使用者,您可以在其中一個 phases 區塊中使用 run-as 來為階段中的命令指定一個使用者。如果未指定 run-as,則會以根使用者身分執行所有命令。

env

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

注意

為了保護敏感資訊,下列項目會在 CodeBuild 日誌中隱藏:

env/殼層

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

對於 Linux 作業系統,支援的殼層標籤包括:

  • bash

  • /bin/sh

對於 Windows 作業系統,支援的殼層標籤包括:

  • powershell.exe

  • cmd.exe

env/variables

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

重要

我們非常不建議在環境變數中存放機密值,尤其是 AWS 存取金鑰 ID 和私密存取金鑰。環境變數可以使用 CodeBuild 主控台和AWS CLI。針對機密值,建議您改為使用 parameter-storesecrets-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 參數存放區的單一自訂環境變數。金鑰是您稍後在構建命令中使用的名稱來引用此自定義環境變量,是存放在 Amazon EC2 Systems Manager 參數存放區的自訂環境變數名稱。若要儲存機密值,請參閱Systems Manager 參數存放區演練:演練 建立和測試 String 參數 (主控台)中的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。指定 Secrets Managerreference-key使用下列模式:

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

<key>

(必要) 區域環境變數名稱。使用此名稱在構建過程中訪問變量。

<secret-id>

(必要) Amazon Resource Name (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 中的金鑰/值組名稱。的索引鍵TestSecretMY_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_ 開頭的環境變數。

env/git-al-助器

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

注意

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

proxy

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

proxy/upload-artifacts

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

proxy/logs

選用的映射。將設定為yes,以便建立 CloudWatch 日誌。預設值為 no

phases

必要的序列。代表在建置的每個階段期間執行的命令 (CodeBuild)。

注意

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

phases/*/run-as

選用的序列。在建置階段中用來指定可執行其命令的 Linux 使用者。如果也在 buildspec 檔案上方為所有命令全域指定 run-as,則階段層級的使用者具有優先權。例如,如果全局run-as指定使用者 1,以及install階段僅run-as語句指定了 User-2,然後 buildspec 文件中的所有命令都以 User-1 運行Except的命令install階段,這些階段以使用者 2 的身份執行。

phase es/*/發生故障

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

  • ABORT-中止構建。

  • CONTINUE-繼續進行下一個階段。

如果未指定此屬性,失敗程序會遵循轉換階段,如建置階段轉換

phase es/*/finally

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

允許的建置階段名稱為:

phases/install

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

phases/install/runtime-versions

選用的序列。執行時間版本可支援 Ubuntu 標準映像 2.0 或更新版本,以及 Amazon Linux 2 標準映像 1.0 或更新版本。如已指定,此區段中至少要包含一個執行時間。使用特定版本指定執行階段,主要版本後跟.x來指定 CodeBuild 使用具有最新次要版本的主要版本,或者latest使用最新的主要和次要版本(例如,java: openjdk11ruby: 2.6nodejs: 12.x, 或java: latest。您可以使用數字或環境變數指定執行時間。例如,如果您使用 Amazon Linux 2 標準映像 2.0,以下指定第 8 版的 Java、Python 第 3 版的最新次要版本,以及已安裝之包含在環境變數中的 Ruby 版本。如需更多詳細資訊,請參閱 由 Code Build 提供的碼頭映像

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

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

如果兩個指定的執行時間發生衝突,則建置會失敗。例如,android: 29java: 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 會依照列出的順序,從頭到尾執行每個命令 (一次一個)。

reports

report-group-name-or-arn

選用的序列。指定傳送報告的目標報告群組。一個專案最多可以擁有五個報告群組。指定現有報告群組的 ARN,或新報告群組的名稱。如果您指定名稱,CodeBuild 會使用您的專案名稱和格式指定的名稱來建立報告群組<project-name>-<report-group-name>。如需更多詳細資訊,請參閱 報告群組命名

reports/<report-group>/files

必要的序列。代表包含由建立產生之測試結果原始資料的位置。包含純量的序列,每個純量代表不同的位置,其中的 CodeBuild 可以在該位置找到測試檔案 (相對於原始組建位置,或如果有設定的話,則為base-directory。位置可能包括下列:

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

  • 子目錄中的單一檔案 (例如,my-subdirectory/my-test-report-file.jsonmy-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

nUnit 3 XML

TESTNGXML

TestNG XML

VISUALSTUDIOTRX

Visual Studio TRX

程式碼涵蓋報告

CLOVERXML

三葉草 XML

COBERTURAXML

科比拉 XML

JACOCOXML

JaCoCo XML

SIMPLECOV

SimpleCov JSON

注意

代碼生成接受由簡單,不簡單的 JSON

reports/<report-group>/base-directory

選用的映射。代表相對於原始組建位置的一或多個上層目錄,該 CodeBuild 用來判斷可以找到原始測試檔案的位置。

reports/<report-group>/discard-paths

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

artifacts

選用的序列。代表 CodeBuild 可以在何處找到組建輸出位置,以及 CodeBuild 如何準備上傳至 S3 輸出儲存貯體的相關資訊。如果您正在建置並將 Docker 影像推送至 Amazon ECR,或是在原始碼上執行單位測試但不進行建置,則此序列不是必要。

artifacts/files

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

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

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

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

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

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

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

artifacts/name

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

  • 您可以使用 CodeBuild API 來創建您的構建和overrideArtifactName旗標設定在ProjectArtifacts物件,當專案更新、建立專案,或組建開始時。

  • 您使用 Codespec 主控台來建立建置,在建置規格檔案中指定了名稱,並且在建置規格檔案中選取啟用語義版本控制當您建立或更新專案時。如需更多詳細資訊,請參閱 建立組建專案 (主控台)

您可以在組建時計算的組建規格檔案中指定名稱。組建規格檔案中指定的名稱使用 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 的所有上層目錄。

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

您可以使用 filesdiscard-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
成品/成品排除路徑

選用的映射。表示一個或多個路徑,相對於base-directory,該 CodeBuild 將從構建工件中排除。

成品/成品啟用符號連結

選用。如果輸出類型為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

cache

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

cache/paths

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

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

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

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

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

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

重要

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

如果您在建立或更新組建專案時,使用 AWS CLI 或 AWS 軟體開發套件來宣告組建規格,則組建規格必須是以 YAML 格式表達的單一字串,並帶有必要的空格字元和換行逸出字元。下一節提供一個範例。

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

您可以使用 Codespec.yml 檔 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/**/*'

這是前述組建規格的範例,以單一字串表達,用於與 AWS CLI 或 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階段,以便與程式碼組建或 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 -yapt-get install -y maven(安裝阿帕奇 Maven),mvn install(用以編譯、測試並將源代碼封裝到組建輸出成品中,並將組建輸出成品安裝在其內部存放區中),docker login(使用對應於自定義環境變量值的密碼登錄到 DockerdockerLoginPassword),以及幾個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

  • 已捨棄 artifactstype 屬性。

  • 在 0.1 版中,AWS CodeBuild 會在建置環境的預設 shell 個別執行個體中執行每個建置命令。在 0.2 版中,CodeBuild 會在建置環境的預設 shell 的相同執行個體中執行所有建置命令。

0.1 這是組建規格格式的初始定義。