ACR 工作參考：YAML

發行項
10/31/2023

「ACR 工作」中的多步驟工作定義提供一個著重於建置、測試及修補容器並以容器為中心的計算原始物件。此文章涵蓋適用於定義您多步驟工作之 YAML 檔案的命令、參數、屬性及語法。

此文章包含適用於為「ACR 工作」建立多步驟工作 YAML 檔案的參考。如果您想要「ACR 工作」的簡介，請參閱 ACR 工作概觀。

acr-task.yaml 檔案格式

「ACR 工作」支援採用標準 YAML 語法的多步驟工作宣告。您會在 YAML 檔案中定義工作步驟。接著，將檔案傳遞至 az acr run 命令，手動執行工作。或者，使用此檔案建立具有 az acr task create 的工作，這會在 Git 認可、基底映像更新或排程時自動觸發。雖然此文章以 acr-task.yaml 作為包含步驟的檔案，但「ACR 工作」支援任何使用支援的副檔名的有效檔案名稱。

最上層 acr-task.yaml 原始物件是工作屬性步驟類型 及 步驟屬性：

工作屬性會套用至整個工作執行的所有步驟。數個全域工作屬性如下：
- version
- stepTimeout
- workingDirectory
工作步驟類型代表可在工作中執行的動作類型。步驟類型有三種：
- build
- push
- cmd
工作步驟屬性是套用至個別步驟的參數。步驟屬性有數個，包括：
- startDelay
- timeout
- when
- ...等等。

接下來是 acr-task.yaml 檔案的基底格式 (包括一些常見的步驟屬性)。雖然這並未完整呈現所有可用的步驟屬性或步驟類型使用方式，但提供一個基本檔案格式的快速概觀。

version: # acr-task.yaml format version.
stepTimeout: # Seconds each step may take.
steps: # A collection of image or container actions.
  - build: # Equivalent to "docker build," but in a multi-tenant environment
  - push: # Push a newly built or retagged image to a registry.
    when: # Step property that defines either parallel or dependent step execution.
  - cmd: # Executes a container, supports specifying an [ENTRYPOINT] and parameters.
    startDelay: # Step property that specifies the number of seconds to wait before starting execution.

支援的工作副檔名

「ACR 工作」保留了數個將視為工作檔案來處理的副檔名，包括 .yaml。所有「未」包含在下列清單中的副檔名都會被「ACR 工作」視為 Dockerfile：.yaml、.yml、.toml、.json、.sh、.bash、.zsh、.ps1、.ps、.cmd、.bat、.ts、.js、.php、.py、.rb、.lua

YAML 是「ACR 工作」目前唯一支援的檔案格式。其他副檔名則保留供可能的未來支援使用。

執行範例工作

此文章接下來的各節中會參考數個範例工作檔案。這些範例工作位於公用 GitHub 存放庫 Azure-Samples/acr-tasks中。您可以使用 Azure CLI 命令 az acr run來執行這些工作。範例命令會類似於：

az acr run -f build-push-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

範例命令的格式會假設您已在 Azure CLI 中設定預設登錄，因此它們會省略 --registry 參數。若要設定預設登錄，請使用 az config 命令加 set 命令，其可接受 defaults.acr=REGISTRY_NAME 索引鍵/值組。

例如，為 Azure CLI 設定一個名為 "myregistry" 的預設登錄：

az config set defaults.acr=myregistry

工作屬性

工作屬性通常會出現在 acr-task.yaml 檔案的頂端，並且是會在整個工作步驟執行過程都套用的全域屬性。這些全域屬性中有些可在個別步驟中被覆寫。

屬性	類型	選用	描述	支援覆寫	預設值
`version`	字串	是	「ACR 工作」服務所剖析的 `acr-task.yaml` 檔案版本。在「ACR 工作」努力維持回溯相容性的同時，此值則可讓「ACR 工作」在已定義的版本內維持相容性。若不指定，預設使用最新版本。	否	無
`stepTimeout`	整數 (秒)	是	步驟的可執行秒數上限。如果在工作上指定 `stepTimeout` 屬性，則會設定所有步驟的預設 `timeout` 屬性。如果在步驟上指定 `timeout` 屬性，則會覆寫工作提供的 `stepTimeout` 屬性。工作的步驟逾時值總和應該等於工作的 run `timeout` 屬性值 (例如，將 `--timeout` 傳遞至 `az acr task create` 命令所設定)。如果工作的 run `timeout` 值較小，則優先使用。	是	600 (10 分鐘)
`workingDirectory`	字串	是	容器在執行階段期間的工作目錄。如果在工作上指定屬性，則會設定所有步驟的預設 `workingDirectory` 屬性。如果在步驟上指定，則會覆寫工作提供的屬性。	是	Windows 的 `c:\workspace` 或 Linux 的 `/workspace`
`env`	[字串, 字串, ...]	是	`key=value` 格式的字串陣列，用來定義工作的環境變數。如果在工作上指定屬性，則會設定所有步驟的預設 `env` 屬性。如果在步驟上指定，則會覆寫繼承自工作的任何環境變數。	是	無
`secrets`	[secret, secret, ...]	是	祕密物件的陣列。	否	None
`networks`	[network, network, ...]	是	網路物件的陣列。	否	None
`volumes`	[volume, volume, ...]	是	磁碟區物件的陣列。指定要掛接至步驟，包含來源內容的磁碟區。	否	None

secret

祕密物件具有下列屬性。

屬性	類型	選用	描述	預設值
`id`	字串	No	祕密的識別碼。	無
`keyvault`	字串	是	Azure Key Vault 祕密 URL。	無
`clientID`	字串	是	Azure 資源之使用者指派受控識別的用戶端識別碼。	無

network

網路物件具有下列屬性。

屬性	類型	選用	描述	預設值
`name`	字串	No	網路的名稱。	無
`driver`	字串	是	管理網路的驅動程式。	無
`ipv6`	bool	是	是否啟用 IPv6 網路功能。	`false`
`skipCreation`	bool	是	是否要略過網路建立。	`false`
`isDefault`	bool	是	網路是否為有提供 Azure Container Registry 的預設網路。	`false`

磁碟區

磁碟區物件具有下列屬性。

屬性	類型	選用	描述	預設值
`name`	字串	No	要掛接的磁碟區名稱。只能包含英數字元、'-' 和 '_'。	無
`secret`	map[string]string	否	每個對應索引鍵都是在磁碟區中建立並填入之檔案的名稱。每個值都是祕密的字串版本。祕密值必須是 Base64 編碼。	無

工作步驟類型

「ACR 工作」支援三種步驟類型。每一種步驟類型都支援數個屬性，詳述於每一種步驟類型的小節中。

步驟類型	Description
`build`	使用熟悉的 `docker build` 語法來建置容器映像。
`push`	執行新建置或重新標記之映像的 `docker push` 以推送至容器登錄。支援 Azure Container Registry、其他私人登錄，以及公用 Docker Hub。
`cmd`	以命令方式執行容器，並將參數傳遞給容器的 `[ENTRYPOINT]`。 `cmd` 步驟類型支援 `env`、`detach` 等參數和其他熟悉的 `docker run` 命令選項，可搭配並行容器執行以進行單元和功能測試。

build

建置容器映像。 build 步驟類型代表一種在雲端中以第一級原始物件形式執行 docker build 的多租用戶、安全方法。

語法：build

version: v1.1.0
steps:
  - [build]: -t [imageName]:[tag] -f [Dockerfile] [context]
    [property]: [value]

執行 az acr run命令以取得 docker 版本。

az acr run -r $ACR_NAME --cmd "docker version" /dev/null

在 yaml 檔案中新增環境變數 DOCKER_BUILDKIT=1 ，以啟用 buildkitbuildkit 和使用 secret 。

build 步驟類型支援下表中的參數。 build 步驟類型也支援 docker build 命令的所有建置選項，例如以 --build-arg 設定建置時間變數。

參數	說明	選用
`-t` \| `--image`	定義所建置映像的完整 `image:tag`。由於映像可能會用於內部工作驗證 (例如功能測試)，因此並非所有映像都需要 `push` 來推送至登錄。不過，若要在工作執行內將某個映像執行個體化，則該映像確實需要一個可供參考的名稱。與 `az acr build` 不同，執行 ACR 工作並不會提供預設的推送行為。使用「ACR 工作」時，預設案例會能夠建置、驗證，然後推送映像。如需了解如何視需要推送所建置的映像，請參閱 push。	是
`-f` \| `--file`	指定傳遞給 `docker build` 的 Dockerfile。如果未指定，則會假設使用內容根目錄中的預設 Dockerfile。若要指定 Dockerfile，請傳遞內容根目錄的相對檔案名稱。	是
`context`	傳遞給 `docker build` 的根目錄。每個工作的根目錄都會設定為共用的 workingDirectory，並且包含相關 Git 複製目錄的根目錄。	否

屬性：build

build 步驟類型支援下列屬性。如需這些屬性的詳細資訊，請參閱本文的工作步驟屬性一節。

屬性	類型	必要
`detach`	bool	選擇性
`disableWorkingDirectoryOverride`	bool	選擇性
`entryPoint`	字串	選用
`env`	[字串, 字串, ...]	選擇性
`expose`	[字串, 字串, ...]	選擇性
`id`	字串	選用
`ignoreErrors`	bool	選擇性
`isolation`	字串	選用
`keep`	bool	選擇性
`network`	物件 (object)	選用
`ports`	[字串, 字串, ...]	選擇性
`pull`	bool	選擇性
`repeat`	int	選擇性
`retries`	int	選擇性
`retryDelay`	整數 (秒)	選擇性
`secret`	物件 (object)	選用
`startDelay`	整數 (秒)	選擇性
`timeout`	整數 (秒)	選擇性
`volumeMount`	物件 (object)	選用
`when`	[字串, 字串, ...]	選擇性
`workingDirectory`	字串	選用

範例：build

建置映像 - 根目錄中的內容

az acr run -f build-hello-world.yaml https://github.com/AzureCR/acr-tasks-sample.git

version: v1.1.0
steps:
  - build: -t $Registry/hello-world -f hello-world.dockerfile .

建置映像 - 子目錄中的內容

version: v1.1.0
steps:
  - build: -t $Registry/hello-world -f hello-world.dockerfile ./subDirectory

push

將一或多個已建置或重新標記的映像推送至登錄。支援推送至私人登錄 (例如 Azure Container Registry) 或公用 Docker Hub。

語法：push

push 步驟類型支援映像集合。 YAML 集合語法支援內嵌和巢狀格式。推送單一映像通常是以內嵌語法表示：

version: v1.1.0
steps:
  # Inline YAML collection syntax
  - push: ["$Registry/hello-world:$ID"]

為了提升可讀性，推送多個映像時，請使用巢狀語法：

version: v1.1.0
steps:
  # Nested YAML collection syntax
  - push:
    - $Registry/hello-world:$ID
    - $Registry/hello-world:latest

屬性：push

push 步驟類型支援下列屬性。如需這些屬性的詳細資訊，請參閱本文的工作步驟屬性一節。

屬性	類型	必要
`env`	[字串, 字串, ...]	選擇性
`id`	字串	選用
`ignoreErrors`	bool	選擇性
`startDelay`	整數 (秒)	選擇性
`timeout`	整數 (秒)	選擇性
`when`	[字串, 字串, ...]	選擇性

範例：push

推送多個映像

az acr run -f build-push-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
  - push: 
    - $Registry/hello-world:$ID

建置、推送及執行

az acr run -f build-run-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
  - push:
    - $Registry/hello-world:$ID
  - cmd: $Registry/hello-world:$ID

cmd

cmd 步驟類型會執行容器。

語法：cmd

version: v1.1.0
steps:
  - [cmd]: [containerImage]:[tag (optional)] [cmdParameters to the image]

屬性：cmd

cmd 步驟類型支援下列屬性：

屬性	類型	必要
`detach`	bool	選擇性
`disableWorkingDirectoryOverride`	bool	選擇性
`entryPoint`	字串	選用
`env`	[字串, 字串, ...]	選擇性
`expose`	[字串, 字串, ...]	選擇性
`id`	字串	選用
`ignoreErrors`	bool	選擇性
`isolation`	字串	選用
`keep`	bool	選擇性
`network`	物件 (object)	選用
`ports`	[字串, 字串, ...]	選擇性
`pull`	bool	選擇性
`repeat`	int	選擇性
`retries`	int	選擇性
`retryDelay`	整數 (秒)	選擇性
`secret`	物件 (object)	選用
`startDelay`	整數 (秒)	選擇性
`timeout`	整數 (秒)	選擇性
`volumeMount`	物件 (object)	選用
`when`	[字串, 字串, ...]	選擇性
`workingDirectory`	字串	選用

您可以在此文章的工作步驟屬性一節中，找到這些屬性的詳細資料。

範例：cmd

執行 hello-world 映像

此命令會執行 hello-world.yaml 工作檔案以參考 Docker Hub 上的 hello-world 映像。

az acr run -f hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - cmd: mcr.microsoft.com/hello-world

執行 bash 映像並回應 "hello world"

此命令會執行 bash-echo.yaml 工作檔案以參考 Docker Hub 上的 bash 映像。

az acr run -f bash-echo.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - cmd: bash echo hello world

執行特定 bash 映像標記

若要執行特定的映像版本，請在 cmd中指定標記。

此命令會執行 bash-echo-3.yaml 工作檔案以參考 Docker Hub 上的 bash:3.0 映像。

az acr run -f bash-echo-3.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - cmd: bash:3.0 echo hello world

執行自訂映像

cmd 步驟類型會使用標準 docker run 格式來參考映像。映像的開頭如果不是登錄，系統會假設其產生自 docker.io。上述範例可同樣表示為：

version: v1.1.0
steps:
  - cmd: docker.io/bash:3.0 echo hello world

藉由使用標準 docker run 映像參考慣例，cmd 便可執行任何私人登錄或公用 Docker Hub 中的映像。如果您要參考「ACR 工作」執行所在之相同登錄中的映像，則不需要指定任何登錄認證。

執行 Azure 容器登錄中的映像。下列範例假設您有名為 myregistry 的登錄和自訂映像 myimage:mytag。
```
version: v1.1.0
steps:
    - cmd: myregistry.azurecr.io/myimage:mytag
```
使用 Run 變數或別名將登錄參考一般化

您可以不將登錄名稱以硬式編碼寫在 acr-task.yaml 檔案中，而是使用 Run 變數或別名來提升其可攜性。 Run.Registry 變數或 $Registry 別名會在執行階段擴充成工作執行所在的登錄名稱。

例如，若要將前述工作一般化，使其能夠在任何 Azure 容器登錄中運作，請在映像名稱中參考 $Registry 變數：
```
version: v1.1.0
steps:
  - cmd: $Registry/myimage:mytag
```

存取祕密磁碟區

volumes 屬性允許在工作的 build 和 cmd 步驟中指定磁碟區及其祕密內容。在每個步驟中，選用的 volumeMounts 屬性會列出要在該步驟中掛接至容器的磁碟區和所對應的容器路徑。祕密會以檔案形式提供到每個磁碟區的掛接路徑。

執行工作，並將兩個祕密掛接至步驟：一個儲存在金鑰保存庫，另一個在命令列中指定：

az acr run -f mounts-secrets.yaml --set-secret mysecret=abcdefg123456 https://github.com/Azure-Samples/acr-tasks.git

# This template demonstrates mounting a custom volume into a container at a CMD step
secrets:
  - id: sampleSecret
    keyvault: https://myacbvault2.vault.azure.net/secrets/SampleSecret # Replace with valid keyvault with access

volumes:
  - name: mysecrets
    secret:
      mysecret1: {{.Secrets.sampleSecret | b64enc}}
      mysecret2: {{.Values.mysecret | b64enc}}

steps:
  - cmd: bash cat /run/test/mysecret1 /run/test/mysecret2
    volumeMounts:
      - name: mysecrets
        mountPath: /run/test

工作步驟屬性

每個步驟類型都支援數個適用於其類型的屬性。下表定義所有可用的步驟屬性。並非所有步驟類型都支援所有屬性。若要查看每個步驟類型可使用這當中哪些屬性，請參閱 cmd、build及 push 步驟類型參考小節。

屬性	類型	選用	描述	預設值
`detach`	bool	是	執行時是否應將容器中斷連結。	`false`
`disableWorkingDirectoryOverride`	bool	是	是否停用 `workingDirectory` 覆寫功能。此選項和 `workingDirectory` 一起使用，可完全控制容器的工作目錄。	`false`
`entryPoint`	字串	是	覆寫步驟容器的 `[ENTRYPOINT]`。	無
`env`	[字串, 字串, ...]	是	`key=value` 格式的字串陣列，用來定義步驟的環境變數。	無
`expose`	[字串, 字串, ...]	是	從容器公開的連接埠陣列。	無
`id`	字串	是	可唯一識別工作內的步驟。工作內的其他步驟可以參考步驟的 `id`，例如使用 `when`進行相依性檢查。 `id` 同時也是執行中容器的名稱。舉例來說，在工作內其他容器中執行的程序可以參考 `id` 作為其 DNS 主機名稱，或藉由 docker logs [id] 來存取它。	`acb_step_%d`，其中 `%d` 是 YAML 檔案中由上而下步驟從 0 開始的索引
`ignoreErrors`	bool	是	不論容器執行期間是否發生錯誤，是否都將步驟標示為成功。	`false`
`isolation`	字串	是	容器的隔離等級。	`default`
`keep`	bool	是	在執行後是否應保留步驟的容器。	`false`
`network`	物件	是	識別容器執行所在的網路。	無
`ports`	[字串, 字串, ...]	是	從容器發佈至主機的連接埠陣列。	無
`pull`	bool	是	是否先強制提取容器再執行容器，以防止任何快取行為。	`false`
`privileged`	bool	是	是否在特殊權限模式中執行容器。	`false`
`repeat`	int	是	重複執行容器的重試次數。	0
`retries`	int	是	如果容器執行失敗則重試的次數。只有當容器的結束代碼非零時，才重試。	0
`retryDelay`	整數 (秒)	是	容器執行重試間隔的延遲秒數。	0
`secret`	物件	是	識別 Azure Key Vault 祕密或 Azure 資源的受控識別。	無
`startDelay`	整數 (秒)	是	延遲執行容器的秒數。	0
`timeout`	整數 (秒)	是	終止步驟前可允許步驟執行的秒數上限。	600
`when`	[字串, 字串, ...]	是	設定步驟與工作內一或多個其他步驟的相依性。	無
`user`	字串	是	容器的使用者名稱或 UID	無
`workingDirectory`	字串	是	設定步驟的工作目錄。「ACR 工作」預設會建立根目錄作為工作目錄。不過，如果您的組建含有數個步驟，則可藉由指定相同的工作目錄，讓較前面的步驟與較後面的步驟共用成品。	Windows 的 `c:\workspace` 或 Linux 的 `/workspace`

volumeMount

volumeMount 物件具有下列屬性。

屬性	類型	選用	描述	預設值
`name`	字串	No	要掛接的磁碟區名稱。必須與 `volumes` 屬性名稱完全相符。	無
`mountPath`	字串	否	在容器中掛接檔案的絕對路徑。	無

範例：工作步驟屬性

範例：id

建置兩個映像，將功能測試映像執行個體化。每個步驟都會由唯一 id 識別，工作中的其他步驟會在其 when 屬性中參考此 id。

az acr run -f when-parallel-dependent.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]
  # run built images to be tested
  - id: hello-world
    cmd: $Registry/hello-world:$ID
    when: ["build-hello-world"]
  - id: func-tests
    cmd: hello-world-test
    env:
      - TEST_TARGET_URL=hello-world
    when: ["hello-world"]
  # push hello-world if func-tests are successful  
  - push: ["$Registry/hello-world:$ID"]
    when: ["func-tests"]

範例：when

when 屬性會指定步驟與工作內其他步驟的相依性。它支援兩個參數值：

when: ["-"] - 表示與其他步驟沒有相依性。指定 when: ["-"] 的步驟將立即開始執行，並可啟用並行步驟執行。
when: ["id1", "id2"] - 表示步驟與 id 為 "id1" 和 id 為 "id2" 的步驟相依。此步驟必須等到 "id1" 和 "id2" 步驟都完成後，才會執行。

如果步驟中未指定 when，則該步驟會取決於 acr-task.yaml 檔案中的前一個步驟是否完成。

不含 when 的循序步驟執行：

az acr run -f when-sequential-default.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
    - cmd: bash echo one
    - cmd: bash echo two
    - cmd: bash echo three

含有 when 的循序步驟執行：

az acr run -f when-sequential-id.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
    - id: step1
      cmd: bash echo one
    - id: step2
      cmd: bash echo two
      when: ["step1"]
    - id: step3
      cmd: bash echo three
      when: ["step2"]

平行映像組建：

az acr run -f when-parallel.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]

平行映像建置和相依測試：

az acr run -f when-parallel-dependent.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]
  # run built images to be tested
  - id: hello-world
    cmd: $Registry/hello-world:$ID
    when: ["build-hello-world"]
  - id: func-tests
    cmd: hello-world-test
    env:
      - TEST_TARGET_URL=hello-world
    when: ["hello-world"]
  # push hello-world if func-tests are successful  
  - push: ["$Registry/hello-world:$ID"]
    when: ["func-tests"]

Run 變數

「ACR 工作」包含一組預設變數，可供工作步驟在執行時使用。使用 {{.Run.VariableName}} 格式即可存取這些變數，其中 VariableName 是下列其中之一：

Run.ID
Run.SharedVolume
Run.Registry
Run.RegistryName
Run.Date
Run.OS
Run.Architecture
Run.Commit
Run.Branch
Run.TaskName

變數名稱一般都簡單易懂。常用變數的詳細資料如下。從 YAML 版本 v1.1.0 起，您可以使用縮寫的預先定義工作別名取代大部分的 run 變數。例如，{{.Run.Registry}} 可以使用 $Registry 別名。

Run.ID

每個 Run (透過 az acr run) 或透過 az acr task create 建立之以觸發程序為基礎的工作執行，都具有唯一識別碼。此識別碼代表目前正在執行的「執行」。

通常用來唯一標記某個映像：

version: v1.1.0
steps:
    - build: -t $Registry/hello-world:$ID .

Run.SharedVolume

所有工作步驟皆可存取之共用磁碟區的唯一識別碼。此磁碟區會掛接至 c:\workspace (Windows) 或 /workspace (Linux)。

Run.Registry

登錄的完整伺服器名稱。通常用來一般參考工作執行所在的登錄。

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID .

Run.RegistryName

容器登錄的名稱。通常用於不需要完整伺服器名稱的工作步驟，例如，在登錄上執行 Azure CLI 命令的 cmd 步驟。

version 1.1.0
steps:
# List repositories in registry
- cmd: az login --identity
- cmd: az acr repository list --name $RegistryName

Run.Date

執行開始的目前 UTC 時間。

Run.Commit

若是由認可至 GitHub 存放庫所觸發的工作，則為認可識別碼。

Run.Branch

若是由認可至 GitHub 存放庫所觸發的工作，則為分支名稱。

別名

自 v1.1.0 起，ACR 工作支援別名，可供工作步驟在執行時使用。別名在概念上類似 bash 和其他一些命令殼層所支援的別名 (命令快速鍵)。

使用別名，只要輸入單字即可啟動任何命令或一組命令 (包括選項和檔案名稱)。

ACR 工作支援數個預先定義的別名，也支援您建立的自訂別名。

預先定義的別名

下列工作別名可用來取代 run 變數：

Alias	Run 變數
`ID`	`Run.ID`
`SharedVolume`	`Run.SharedVolume`
`Registry`	`Run.Registry`
`RegistryName`	`Run.RegistryName`
`Date`	`Run.Date`
`OS`	`Run.OS`
`Architecture`	`Run.Architecture`
`Commit`	`Run.Commit`
`Branch`	`Run.Branch`

在工作步驟中，在別名前面加上 $ 指示詞，如以下範例所示：

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .

映像別名

下列每個別名都會指向 Microsoft Container Registry (MCR) 中的穩定映像。您可以在工作檔案的 cmd 區段中參照它們每一個，不使用指示詞。

Alias	映像
`acr`	`mcr.microsoft.com/acr/acr-cli:0.5`
`az`	`mcr.microsoft.com/acr/azure-cli:7ee1d7f`
`bash`	`mcr.microsoft.com/acr/bash:7ee1d7f`
`curl`	`mcr.microsoft.com/acr/curl:7ee1d7f`

下列範例工作會使用數個別名，清除執行登錄之存放庫 samples/hello-world 中超過 7 天的映像標籤：

version: v1.1.0
steps:
  - cmd: acr tag list --registry $RegistryName --repository samples/hello-world
  - cmd: acr purge --registry $RegistryName --filter samples/hello-world:.* --ago 7d

自訂別名

在 YAML 檔案中定義自訂別名，並依下例所示運用。別名只能包含英數字元。擴充別名的預設指示詞是 $ 字元。

version: v1.1.0
alias:
  values:
    repo: myrepo
steps:
  - build: -t $Registry/$repo/hello-world:$ID -f Dockerfile .

您可以連結到遠端或本機 YAML 檔案，以取得自訂別名定義。下列範例會連結到 Azure Blob 儲存體中的 YAML 檔案：

version: v1.1.0
alias:
  src:  # link to local or remote custom alias files
    - 'https://link/to/blob/remoteAliases.yml?readSasToken'
[...]

後續步驟

如需多步驟工作的概觀，請參閱執行 ACR 工作中的多步驟建置、測試及修補工作。

如需了解單一步驟建置，請參閱 ACR 工作概觀。