Use substitutions
em seu arquivo de configuração da build para substituir variáveis
específicas no momento da build.
As substituições são úteis para variáveis cujo valor não é conhecido até o momento da criação ou para reutilizar uma solicitação de versão existente com diferentes valores variáveis.
O Cloud Build fornece substituições integradas ou você pode definir as próprias substituições. Use substitutions
no steps
e no images
do build para resolver os valores no tempo da compilação.
Nesta página, explicamos como usar substituições padrão ou definir sua própria substitutions
.
Como usar substituições padrão
O Cloud Build fornece as seguintes substituições padrão para todas as versões:
$PROJECT_ID
: ID do projeto do Cloud$BUILD_ID
: ID da sua versão$PROJECT_NUMBER
: o ID do seu projeto$LOCATION
: a região associada ao build.
O Cloud Build fornece as seguintes substituições padrão para versões invocadas por gatilhos:
$TRIGGER_NAME
: o nome associado ao gatilho$COMMIT_SHA
: o ID de confirmação associado à sua versão$REVISION_ID
: o ID de confirmação associado à sua versão$SHORT_SHA
: os primeiros sete caracteres deCOMMIT_SHA
$REPO_NAME
: o nome do seu repositório$BRANCH_NAME
: o nome da sua ramificação$TAG_NAME
: o nome da sua tag$REF_NAME
: o nome da ramificação ou da tag$TRIGGER_BUILD_CONFIG_PATH
: o caminho para o arquivo de configuração do build usado durante a execução; caso contrário, uma string vazia se o build estiver configurado inline no gatilho ou usar umDockerfile
ouBuildpack
O Cloud Build fornece as seguintes substituições padrão específicas do GitHub disponíveis para acionadores de solicitação de envio:
$_HEAD_BRANCH
: head branch da solicitação de envio$_BASE_BRANCH
: base branch da solicitação de envio$_HEAD_REPO_URL
: url da head repo da solicitação de envio$_PR_NUMBER
: número da solicitação de envio
Se uma substituição padrão não estiver disponível, como versões sem código-fonte ou versões que usam um código-fonte do armazenamento, as ocorrências em que as variáveis estão ausentes serão substituídas por uma string vazia.
Ao iniciar uma versão usando gcloud builds submit
, é possível especificar variáveis que normalmente viriam de versões acionadas com o --substitutions
argumento. Mais especificamente, você pode fornecer manualmente valores para:
$TRIGGER_NAME
$COMMIT_SHA
$REVISION_ID
$SHORT_SHA
$REPO_NAME
$BRANCH_NAME
$TAG_NAME
$REF_NAME
$TRIGGER_BUILD_CONFIG_PATH
Por exemplo, o seguinte comando usa a substituição TAG_NAME
:
gcloud builds submit --config=cloudbuild.yaml \
--substitutions=TAG_NAME="test"
O exemplo a seguir usa as substituições padrão $BUILD_ID
, $PROJECT_ID
, $PROJECT_NUMBER
e $REVISION_ID
.
YAML
steps:
# Uses the ubuntu build step:
# to run a shell script; and
# set env variables for its execution
- name: 'ubuntu'
args: ['bash', './myscript.sh']
env:
- 'BUILD=$BUILD_ID'
- 'PROJECT_ID=$PROJECT_ID'
- 'PROJECT_NUMBER=$PROJECT_NUMBER'
- 'REV=$REVISION_ID'
# Uses the docker build step to build an image called my-image
- name: 'gcr.io/cloud-builders/docker'
args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-image', '.']
# my-image is pushed to Container Registry
images:
- 'gcr.io/$PROJECT_ID/my-image'
JSON
{
"steps": [{
"name": "ubuntu",
"args": [
"bash",
"./myscript.sh"
],
"env": [
"BUILD=$BUILD_ID",
"PROJECT_ID=$PROJECT_ID",
"PROJECT_NUMBER=$PROJECT_NUMBER",
"REV=$REVISION_ID"
]
}, {
"name": "gcr.io/cloud-builders/docker",
"args": ["build", "-t", "gcr.io/$PROJECT_ID/my-image", "."]
}],
"images": [
"gcr.io/$PROJECT_ID/my-image"
]
}
No exemplo abaixo, mostramos o uso da etapa de criação docker
por uma solicitação de versão para criar uma imagem e transmiti-la para o Container Registry usando a substituição padrão $PROJECT_ID
:
Neste exemplo:
- A solicitação de versão tem uma etapa de criação que usa
docker
emgcr.io/cloud-builders
para criar a imagem do Docker.- Os argumentos que serão passados para o comando
docker
são especificados pelo campoargs
. Neste caso,build -t gcr.io/my-project/cb-demo-img .
será invocado depois da substituição de$PROJECT_ID
pelo ID do projeto.
- Os argumentos que serão passados para o comando
O campo
images
contém o nome da imagem. Se a versão for bem-sucedida, a imagem resultante será transmitida para o Container Registry. Se a versão não criar a imagem corretamente, ela falhará.
YAML
steps:
- name: gcr.io/cloud-builders/docker
args: ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."]
images:
- gcr.io/$PROJECT_ID/cb-demo-img
JSON
{
"steps": [{
"name": "gcr.io/cloud-builders/docker",
"args": ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."]
}],
"images": [
"gcr.io/$PROJECT_ID/cb-demo-img"
]
}
Como usar substituições definidas pelo usuário
Você também pode definir suas próprias substituições. As substituições definidas pelo usuário precisam obedecer às seguintes regras:
- É obrigatório que as substituições comecem com um sublinhado (
_
) e que sejam usadas somente letras maiúsculas e números (respeitando a expressão regular_[A-Z0-9_]+
). Isso evita conflitos com substituições integradas. Para usar uma expressão que comece com$
, use$$
. Sendo assim,$FOO
é inválido porque não é uma substituição integrada.$$FOO
avalia de acordo com a string literal$FOO
.
- O número de parâmetros é limitado a 100. O comprimento de uma chave de parâmetro é limitado a 100 bytes e o comprimento de um valor de parâmetro é limitado a 4000 bytes.
É possível especificar variáveis de duas maneiras: $_FOO
ou ${_FOO}
:
- Tanto
$_FOO
quanto${_FOO}
avaliam o valor de_FOO
. No entanto,${}
permite que a substituição funcione sem espaços ao redor, o que permite substituições como${_FOO}BAR
. $$
permite que você inclua um$
literal no modelo. Sendo assim,$_FOO
avalia de acordo com o valor de_FOO
.$$_FOO
avalia de acordo com a string literal$_FOO
.$$$_FOO
é avaliado de acordo com a string literal$
seguida do valor de_FOO
.
Nas substituições, use o argumento --substitutions
no comando gcloud
ou especifique-o no arquivo de configuração.
O exemplo a seguir mostra uma configuração de versão com duas substituições definidas pelo usuário, chamadas _NODE_VERSION_1
e _NODE_VERSION_2
.
YAML
steps:
- name: 'gcr.io/cloud-builders/docker'
args: ['build',
'--build-arg',
'node_version=${_NODE_VERSION_1}',
'-t',
'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}',
'.']
- name: 'gcr.io/cloud-builders/docker'
args: ['build',
'--build-arg',
'node_version=${_NODE_VERSION_2}',
'-t',
'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}',
'.']
substitutions:
_NODE_VERSION_1: v6.9.1 # default value
_NODE_VERSION_2: v6.9.2 # default value
images: [
'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}',
'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}'
]
JSON
{
"steps": [{
"name": "gcr.io/cloud-builders/docker",
"args": [
"build",
"--build-arg",
"node_version=${_NODE_VERSION_1}",
"-t",
"gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}",
"."
]
}, {
"name": "gcr.io/cloud-builders/docker",
"args": [
"build",
"--build-arg",
"node_version=${_NODE_VERSION_2}",
"-t",
"gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}",
"."
]
}],
"substitutions": {
"_NODE_VERSION_1": "v6.9.1"
"_NODE_VERSION_1": "v6.9.2"
},
"images": [
"gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}",
"gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}"
]
}
Para modificar o valor de substituição especificado no arquivo de configuração da criação, use a sinalização --substitutions
no comando gcloud builds submit
. As substituições são um mapeamento de variáveis para valores, em vez de matrizes ou sequências. É possível substituir os valores de variáveis de substituição padrão, exceto $PROJECT_ID
e $BUILD_ID
. O comando a seguir modifica o valor padrão de _NODE_VERSION_1
especificado no arquivo de configuração da criação acima:
gcloud builds submit --config=cloudbuild.yaml \
--substitutions=_NODE_VERSION_1="v6.9.4",_NODE_VERSION_2="v6.9.5" .
Por padrão, a versão retornará um erro se faltar uma variável de substituição ou uma substituição. No entanto, é possível definir a opção ALLOW_LOOSE
para pular essa verificação.
O snippet a seguir imprime "hello world" e define uma substituição não usada.
Como a opção de substituição ALLOW_LOOSE
está definida, a versão será bem-sucedida, mesmo considerando a substituição ausente.
YAML
steps:
- name: 'ubuntu'
args: ['echo', 'hello world']
substitutions:
_SUB_VALUE: unused
options:
substitution_option: 'ALLOW_LOOSE'
JSON
{
"steps": [
{
"name": "ubuntu",
"args": [
"echo",
"hello world"
]
}
],
"substitutions": {
"_SUB_VALUE": "unused"
},
"options": {
"substitution_option": "ALLOW_LOOSE"
}
}
se o build for invocado por um gatilho, a opção ALLOW_LOOSE
será definida por padrão. Nesse caso, o build não retornará um erro se houver uma variável de substituição ausente ou uma substituição ausente. Não é possível modificar a opção ALLOW_LOOSE
para builds invocados por acionadores.
Se a opção ALLOW_LOOSE
não for especificada, as chaves sem correspondência no mapeamento de substituições ou na solicitação do build resultarão em erro. Por exemplo, se a solicitação de build incluir $_FOO
e o mapeamento de substituições não definir _FOO
, você receberá um erro depois de executar o build ou invocar um gatilho se o acionador inclui variáveis de substituição.
As variáveis de substituição a seguir sempre contêm um valor padrão de string vazia, mesmo que você não defina a opção ALLOW_LOOSE
:
$REPO_NAME
$BRANCH_NAME
$TAG_NAME
$COMMIT_SHA
$SHORT_SHA
Ao definir uma variável de substituição, você não está limitado a strings estáticas. Você também tem acesso ao payload do evento que invocou o gatilho. Eles estão disponíveis como vinculações de payload. Também é possível aplicar expansões de parâmetro bash em variáveis de substituição e armazenar a string resultante como uma nova variável de substituição. Para saber mais, consulte Como usar vinculações de payload e expansões de parâmetros bash em substituições.
Substituições dinâmicas
Você pode referenciar o valor de outra variável em uma substituição
definida pelo usuário configurando a opção dynamic_substitutions
para true
no
arquivo de configuração do build. Se o build for invocado por um gatilho, o
campo dynamic_substitutions
será sempre definido para true
e não precisará
ser especificado no arquivo de configuração do build. Se a versão for invocada manualmente,
defina o campo dynamic_substitutions
para true
para que as expansões de parâmetro bash
sejam interpretadas ao executar o build.
O arquivo de configuração do build a seguir mostra a variável de substituição ${_IMAGE_NAME}
fazendo referência à variável ${PROJECT_ID}
. O
campo dynamic_substitutions
está definido como true
. Portanto, a referência
é aplicada ao invocar um build manualmente:
YAML
steps:
- name: 'gcr.io/cloud-builders/docker'
args: ['build', '-t', '${_IMAGE_NAME}', '.']
substitutions:
_IMAGE_NAME: 'gcr.io/${PROJECT_ID}/test-image'
options:
dynamic_substitutions: true
JSON
{
"steps": [
{
"name": "gcr.io/cloud-builders/docker",
"args": [
"build",
"-t",
"${_IMAGE_NAME}",
"."
]
}
],
"substitutions": {
"_IMAGE_NAME": "gcr.io/${PROJECT_ID}/test-image"
},
"options": {
"dynamic_substitutions": true
}
}
Para mais informações, consulte Como aplicar expansões de parâmetros bash.
A seguir
- Saiba como usar vinculações de payload e expansões de parâmetros bash em substituições.
- Saiba como criar um arquivo de configuração de compilação básico.
- Saiba como criar e gerenciar gatilhos de compilação.
- Saiba como executar builds manualmente no Cloud Build.