Como substituir valores variáveis

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 de COMMIT_SHA
$REPO_NAME: o nome do seu repositório
$REPO_FULL_NAME: o nome completo do repositório, incluindo o usuário ou a organização
$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 um Dockerfile ou Buildpack

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 --substitutionsargumento. Mais especificamente, você pode fornecer manualmente valores para:

$TRIGGER_NAME
$COMMIT_SHA
$REVISION_ID
$SHORT_SHA
$REPO_NAME
$REPO_FULL_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 em gcr.io/cloud-builders para criar a imagem do Docker.
- Os argumentos que serão passados para o comando docker são especificados pelo campo args. Neste caso, build -t gcr.io/my-project/cb-demo-img . será invocado depois da substituição de $PROJECT_ID pelo ID do projeto.
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:
    substitutionOption: '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 de string vazia padrão, mesmo que você não defina a opção ALLOW_LOOSE:

$REPO_NAME
$REPO_FULL_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 dynamicSubstitutions para true no arquivo de configuração do build. Se o build for invocado por um gatilho, o campo dynamicSubstitutions 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 dynamicSubstitutions para true para que as expansões de parâmetro bash sejam interpretadas ao executar o build.

O arquivo de configuração de build a seguir mostra a variável de substituição ${_IMAGE_NAME} que faz referência à variável ${PROJECT_ID}. O campo dynamicSubstitutions está definido como true para que a referência seja 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:
    dynamicSubstitutions: 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.

Como mapear substituições para variáveis de ambiente

Os scripts não são compatíveis diretamente com substituições, mas são compatíveis com variáveis de ambiente. Você pode mapear substituições para variáveis de ambiente de forma automática de uma só vez ou manualmente, definindo cada variável de ambiente.

Substituições de mapas automaticamente

No nível da versão. Para mapear automaticamente todas as substituições para variáveis de ambiente, que estarão disponíveis em todo o build, defina automapSubstitutions como true como uma opção no nível do build. Por exemplo, o arquivo de configuração da versão a seguir mostra a substituição definida pelo usuário $_USER e a substituição padrão $PROJECT_ID mapeada para variáveis de ambiente:

YAML

steps:
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Hello $_USER"
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Your project ID is $PROJECT_ID"
options:
  automapSubstitutions: true
substitutions:
  _USER: "Google Cloud"

JSON

{
  "steps": [
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
    },
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'"
    }
  ],
  "options": {
    "automap_substitutions": true
  },
  "substitutions": {
    "_USER": "Google Cloud"
  }
}

No nível da etapa. Para mapear automaticamente todas as substituições e disponibilizá-las como variáveis de ambiente em uma única etapa, defina o campo automapSubstitutions como true nessa etapa. No exemplo a seguir, somente a segunda etapa mostrará as substituições corretamente, porque é a única com o mapeamento de substituições automáticas ativado:

YAML

steps:
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Hello $_USER"
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Your project ID is $PROJECT_ID"
  automapSubstitutions: true
substitutions:
  _USER: "Google Cloud"

JSON

{
  "steps": [
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
    },
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'",
      "automap_substitutions": true
    }
  ],
  },
  "substitutions": {
    "_USER": "Google Cloud"
  }

Além disso, é possível disponibilizar as substituições como variáveis de ambiente em toda a versão e ignorá-las em uma etapa. Defina automapSubstitutions como true no nível do build e defina o mesmo campo como false na etapa em que você quer ignorar as substituições. No exemplo a seguir, mesmo que as substituições de mapeamento estejam ativadas no nível da versão, o ID do projeto não será impresso na segunda etapa, porque automapSubstitutions está definido como false nessa etapa:

YAML

steps:
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Hello $_USER"
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Your project ID is $PROJECT_ID"
    automapSubstitutions: false
options:
  automapSubstitutions: true
substitutions:
  _USER: "Google Cloud"

JSON

{
  "steps": [
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
    },
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'",
      "automap_substitutions": false
    }
  ],
  "options": {
    "automap_substitutions": true
  },
  },
  "substitutions": {
    "_USER": "Google Cloud"
  }

Substituir substituições manualmente

Você pode mapear manualmente as substituições para variáveis de ambiente. Cada variável de ambiente é definida no nível da etapa usando o campo env, e o escopo das variáveis é restrito à etapa em que elas são definidas. Esse campo usa uma lista de chaves e valores.

O exemplo a seguir mostra como mapear a substituição $PROJECT_ID para a variável de ambiente BAR:

YAML

steps:
- name: 'ubuntu'
  env:
  - 'BAR=$PROJECT_ID'
  script: 'echo $BAR'

JSON

{
  "steps": [
    {
      "name": "ubuntu",
      "env": [
        "BAR=$PROJECT_ID"
      ],
      "script": "echo $BAR"
    }
  ]
}

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.