Passos do Latchkey

Como um passo do Latchkey é executado#

Quando o Latchkey compila o seu arquivo de workflow, ele copia os comandos do passo para o seu plano. O passo então roda como um passo do seu job, no runner do seu job e com o env: do seu job. O plano registra a versão e o digest do passo. Uma versão publicada nunca muda, então um commit sempre roda os mesmos comandos, inclusive numa reexecução.

latchkey/setup-node define NPM_CONFIG_PREFIX, latchkey/setup-python adiciona o bin do seu ambiente virtual ao fim do PATH e latchkey/setup-java define JAVA_HOME, cada um para todos os passos do job, inclusive os anteriores a ele. Uma variável que o seu arquivo de workflow define em um env:, seja o do workflow, o do job ou o de um passo, prevalece sobre uma que um passo do Latchkey define, e quando dois passos do Latchkey definem a mesma variável, vale o valor do passo posterior. Um passo pulado ainda definiria a sua variável, então esses três passos não aceitam if:. Para usar um deles só em algumas execuções, coloque-o em um job próprio e escreva o if: nesse job; para usar mais de uma versão, escolha a versão por uma matrix.

Como escrever um#

Um passo aceita name:, uses:, with:, env: e if:, e roda run: ou uses:, nunca os dois. Em with:, escreva cada entrada como um valor direto, a partir de um valor da matrix, como um ${{ needs.<job>.outputs.<name> }} inteiro, ou como um mapa de branches que escolhe um valor direto pela branch da execução, como o environment: de um job pode fazer (veja Arquivos de workflow). Um secret nunca vai em with:: o passo lê um secret do seu env:, como um passo run: faz.

Fixe uma versão exata. @1, @latest e a ausência de versão são recusados, e a recusa mostra as versões publicadas.

latchkey/cache-restore#

Restaura uma entrada do cache do Latchkey em um diretório. Uma falha de cache não restaura nada, e o job continua. Entradas: key (obrigatória; de 1 a 200 letras, dígitos, ., _ ou -), version (obrigatória; de 1 a 64 dos mesmos caracteres; outra versão é outra entrada) e into (padrão .; um caminho dentro do workspace, ou ~ para o diretório home).

A versão 1.1.0 também aceita hash-files, descrito em latchkey/cache-save.

latchkey/cache-save#

Salva caminhos em uma entrada do cache do Latchkey. Uma entrada que já existe é mantida, e o job continua. Entradas: key e version (obrigatórias, como em latchkey/cache-restore), from (padrão .; o diretório a que os caminhos se referem, dentro do workspace ou do diretório home) e path (obrigatória; um ou mais caminhos dentro de from, separados por espaços).

Os dois passos usam o mesmo cache que latchkey cache restore e latchkey cache save: ele é restrito ao repositório e à branch, as outras branches leem o cache da branch padrão, e as entradas ficam guardadas por 14 dias. Um pull request de um fork não recebe nenhum cache, então seus passos não restauram nada e não salvam nada, e o job continua.

A versão 1.1.0 de cada um também aceita hash-files: padrões de arquivos rastreados no repositório, separados por espaços. O passo adiciona ao fim de key um hash do conteúdo deles como está no commit, então uma mudança no lockfile cria uma nova entrada, como o hashFiles() do GitHub faz em uma chave. Um padrão que não corresponde a nenhum arquivo rastreado ainda gera a mesma chave em toda execução.

latchkey/setup-node#

Troca o Node e o npm do runner por uma versão que a imagem do runner traz, para todos os passos seguintes. Entrada: node-version (obrigatória; como 22, 22.23 ou 22.23.3; uma versão major, ou major e minor, pega a versão mais nova desse tipo na imagem). Uma versão que a imagem não traz faz o passo falhar, e o passo mostra as versões que ela traz. A versão 1.0.1 também funciona em um job de um pull request de um fork, onde a versão 1.0.0 falha.

latchkey/setup-python#

Cria um ambiente virtual em ~/.latchkey/venv a partir de uma versão do Python que a imagem do runner traz, e troca python, python3, pip e pip3 por ele em todos os passos seguintes, então um pip install simples instala nele. Os comandos do ambiente, como um que um pacote instala, ficam no PATH depois dos da própria imagem, então, quando a imagem já tem um comando com esse nome, roda o da imagem. Entrada: python-version (obrigatória; uma versão menor, como 3.12 ou 3.13; a imagem traz uma versão de cada). Uma versão que a imagem não traz faz o passo falhar, e o passo mostra as versões que ela traz. O Python da própria imagem não muda, e dentro do ambiente pip install --user é recusado.

latchkey/setup-go#

Troca o Go do runner por uma versão que a imagem do runner traz, para todos os passos seguintes. Entrada: go-version (obrigatória; como 1.25 ou 1.25.8; uma versão minor pega o patch mais novo dela na imagem). Uma versão que a imagem não traz faz o passo falhar, e o passo mostra as versões que ela traz. Um job de um pull request de um fork não pode usar sudo, então o passo falha ali.

latchkey/setup-java#

Troca o Java do runner por um JDK Temurin que a imagem do runner traz, para todos os passos seguintes, e define JAVA_HOME para ele no job inteiro. Entrada: java-version (obrigatória; uma versão major como 17 ou 21). Uma versão que a imagem não traz faz o passo falhar, e o passo mostra as versões que ela traz. Um job de um pull request de um fork não pode usar sudo, então o passo falha ali.

latchkey/npm-publish#

Publica o pacote em directory (padrão .) com o token em NODE_AUTH_TOKEN, que o passo lê do seu env:, definido a partir de um secret. Entradas: tag (padrão latest), access (public ou restricted), dry-run (padrão false) e registry (padrão https://registry.npmjs.org/). Sem token, o passo falha, a menos que dry-run seja true. Um job de um pull request de um fork não recebe nenhum secret, então ali o passo só pode rodar com dry-run: true, que não publica nada.

latchkey/docker-build-push#

Constrói a imagem em context (padrão .) a partir de file (padrão o seu Dockerfile) e a marca com cada referência em tags (obrigatória, separadas por espaços). Com push: true ele as envia, e com o padrão false carrega a imagem no Docker do runner para os passos seguintes. Com username definido, ele faz login em registry (padrão Docker Hub) com a senha de DOCKER_PASSWORD no env: do passo. Um job de um pull request de um fork não pode usar Docker, então o passo falha ali.

latchkey/aws-login#

Faz o login do job na AWS como uma role do IAM, com o token de identidade do Latchkey do job, para todos os passos seguintes. Entradas: role-to-assume (obrigatória; o ARN da role), aws-region (obrigatória), role-session-name (padrão latchkey) e role-duration-seconds (padrão 3600; de 900 a 43200, e não mais que a sessão máxima da role). A role precisa confiar no emissor do Latchkey para o seu repositório, com o público sts.amazonaws.com. Em uma execução de ensaio, e quando o pipeline do job está em ensaio, o token de identidade do job traz um sub que começa com advisory:, que uma confiança escrita para execuções reais não aceita. O AWS CLI e os SDKs dos passos seguintes leem a role da configuração AWS do job e buscam novas credenciais antes que as antigas expirem, então um job longo continua funcionando. Nenhuma chave entra no ambiente de nenhum passo, e o passo não define nenhuma variável de ambiente: a região está na configuração AWS, não em AWS_REGION. Uma ferramenta que lê credenciais da AWS só de variáveis de ambiente não recebe nenhuma deste passo. Um job de um pull request de um fork não tem token de identidade, então o passo falha ali.

latchkey/artifact-upload#

Envia caminhos como um único artefato desta execução, para os jobs que precisam deste job. Entradas: name (obrigatória; de 1 a 128 letras, dígitos, ., _ ou -, e não . nem ..), from (padrão .; o diretório a que os caminhos se referem, dentro do workspace ou do diretório home), path (obrigatória; um ou mais caminhos dentro de from, separados por espaços) e include-hidden-files (padrão false). O artefato guarda cada caminho como ele está sob from, então, para enviar o que um diretório contém, defina from como ele e path como .. Arquivos e diretórios cujo nome começa com um ponto ficam de fora, a menos que include-hidden-files seja true, e um envio que nomeia um deles, ou que não encontra nenhum arquivo regular, falha.

latchkey/artifact-download#

Baixa um artefato que um job nomeado em needs: deste job enviou e o extrai em um diretório. Entradas: name (obrigatória) e into (padrão .; um caminho dentro do workspace ou do diretório home, criado se ainda não existir). O artefato é conferido com o que foi enviado antes de qualquer extração, e um que contenha um caminho fora de into é recusado, e nada é extraído.

Os dois passos usam os mesmos artefatos que latchkey artifact upload e latchkey artifact download, com os mesmos nomes e limites, e um artefato fica guardado por 7 dias (veja Arquivos de workflow). Ao contrário dos passos de cache, um envio ou download que falha faz o passo falhar. Um job de um pull request de um fork não pode usar artefatos, então os dois passos falham nele.

O que o Latchkey recusa#

O Latchkey recusa um arquivo em vez de rodá-lo com um passo que não consegue ler, e mostra a linha: um uses: fora de latchkey/, um nome de passo que ele não publica, uma versão que não é exata ou não foi publicada, uma entrada ausente, desconhecida ou fora da regra, run: e uses: no mesmo passo, e with: em um passo run:. Cada recusa diz o que escrever no lugar.