Este documento descreve a sintaxe do arquivo .gitlab-ci.yml, que é utilizado para gerenciar as tarefas do runner de um projeto. Para uma introdução rápida ao GitLab CI, consulte o guia de início rápido.

A partir da versão 7.12, o GitLab CI utiliza arquivos YAML (.gitlab-ci.yml) para configurar projetos. Este arquivo, localizado na raiz do repositório, define como o projeto será construído.

Definição de Tarefas

Antes da construção, o arquivo YAML define uma série de tarefas com suas respectivas restrições. Cada tarefa começa com seu nome e deve incluir obrigatoriamente a seção script:

job1:
 script: executar-script-para-job1

job2:
 script: executar-script-para-job2

Este exemplo demonstra uma configuração de CI simples com duas tarefas independentes, cada uma executando um comando diferente. O script pode executar comandos do sistema (ex: ./configure && make && make install) ou scripts (ex: test.sh).

As tarefas são gerenciadas pelos Runners e executadas pelos servidores onde os runners estão configurados. É importante notar que cada tarefa é executada em um ambiente isolado.

Um exemplo mais complexo ilustrando a sintaxe YAML:

image: ruby:2.1
services:
 - postgres

before_script:
 - bundle install

after_script:
 - rm secrets

stages:
 - build
 - test
 - deploy

job1:
 stage: build
 script:
   - executar-script-para-job1
 only:
   - master
 tags:
   - docker

Palavras-chave Reservadas

As seguintes palavras-chave são reservadas e não podem ser usadas como nomes de tarefas (jobs):

Palavra-chave	Obrigatório	Descrição
image	Não	Define a imagem Docker a ser utilizada. Consulte a documentação do Docker.
services	Não	Define os serviços Docker a serem utilizados. Consulte a documentação do Docker.
stages	Não	Define os estágios (stages) de construção.
types	Não	Alias para stages (descontinuado).
before_script	Não	Define comandos a serem executados antes de cada job.
after_script	Não	Define comandos a serem executados após cada job.
variables	Não	Define variáveis de ambiente para a construção.
cache	Não	Define um conjunto de arquivos a serem cacheados para uso em execuções subsequentes.

image e services

Essas palavras-chave permitem o uso de uma imagem Docker customizada e uma lista de serviços durante todo o ciclo de vida de um job. Para detalhes de configuração, consulte a documentação específica.

before_script

before_script é utilizado para definir comandos que serão executados antes de todos os jobs, incluindo os de deploy, mas após a recuperação de artefatos. Pode ser uma lista de strings ou uma string multilinha.

after_script

Introduzido a partir do GitLab 8.7 (requer GitLab Runner v1.2), after_script define comandos a serem executados após todos os jobs. Deve ser uma lista de strings ou uma string multilinha.

stages

stages define os estágios que podem ser chamados pelos jobs, permitindo pipelines com múltiplos níveis. A ordem dos elementos em stages determina a sequência de execução dos jobs:

1. Jobs no mesmo estágio podem ser executados em paralelo.
2. Jobs do próximo estágio só começam após o sucesso de todos os jobs do estágio anteiror.

Considerando o seguinte exemplo com 3 estágios:

stages:
- build
- test
- deploy

1. Primeiramente, todos os jobs com stage: build são executados em paralelo.
2. Após o sucesso de todos os jobs de build, os jobs de test começam a ser executados em paralelo.
3. Após o sucesso de todos os jobs de test, os jobs de deploy começam a ser executados em paralelo.
4. Após o sucesso de todos os jobs de deploy, o commit é marcado como success.
5. Se qualquer job em um estágio anterior falhar, o commit é marcado como failed e os jobs dos estágios subsequentes não são executados.

Existem dois casos especiais:

1. Se stages não for definido em .gitlab-ci.yml, os estágios padrão serão build, test e deploy.
2. Se um job não especificar um stage, ele será automaticamente alocado ao estágio test.

types

Descontinuado e será removido na versão 10.0. Use stages em vez disso. Possui a mesma funcionalidade que stages.

variables

Introduzido a partir do GitLab Runner V0.5.0. O GitLab CI permite a adição de variáveis no arquivo .gitlab-ci.yml, que estarão disponíveis no ambiente do job. Como essas configurações são armazenadas no repositório Git, é recomendado usá-las para configurações não sensíveis do projeto:

variables:
 DATABASE_URL:"postgres://postgres@postgres/my_database"

Essas variáveis podem ser usadas em comandos e scripts subsequentes. Contêineres de serviço também podem utilizar variáveis definidas no YAML, permitindo um bom controle sobre eles. As variáveis também podem ser definidas em nível de job.

Além das variáveis customizadas pelo usuário, o Runner pode definir suas próprias variáveis. CI_COMMIT_REG_NAME é um bom exemplo, cujo valor representa o nome do branch ou tag usado para construir o projeto. Além de definir variáveis em .gitlab-ci.yml, elas podem ser configuradas como variáveis privadas na interface do GitLab.

Para mais informações sobre variáveis, consulte a documentação.

cache

Introduzido a partir do GitLab Runner v0.7.0. cache especifica arquivos ou diretórios que devem ser cacheados entre os jobs. Apenas caminhos dentro do diretório de trabalho do projeto podem ser utilizados.

A partir do GitLab 9.0, pipelines e jobs têm o cache habilitado por padrão.

Se cache for definido fora do escopo dos jobs, ele se torna um cache global acessível por todos os jobs.

Cache de arquivos em binaries e .config:

rspec:
 script: test
 cache:
   paths:
   - binaries/
   - .config

Cache de arquivos não rastreados pelo Git:

rspec:
 script: test
 cache:
   untracked: true

Cache de arquivos não rastreados dentro de binaries:

rspec:
 script: test
 cache:
   untracked: true
   paths:
   - binaries/

A configuração de cache em nível de job tem prioridade sobre a configuração global. O job rspec a seguir só irá cachear arquivos dentro de binaries/:

cache:
 paths:
 - my/files

rspec:
 script: test
 cache:
   key: rspec
   paths:
   - binaries/

É importante notar que o cache é compartilhado antes da execução dos jobs. Se diferentes jobs precisam cachear caminhos de arquivos distintos, é necessário definir cache:key diferentes para cada um, caso contrário, o conteúdo do cache pode ser sobrescrito.

O cache é uma tentativa, portanto, não há garantia de que ele estará sempre disponível. Consulte a documentação do GitLab Runner para mais detalhes.

cache:key

Introduzido a partir do GitLab Runner v1.0.0. A diretiva key permite definir o escopo do cache (afinidade), podendo ser um cache único para todos os jobs, um por job, um por branch, ou qualquer outra configuração desejada.

Ela também possibilita um ajuste fino do cache, permitindo a configuração de caches diferentes para jobs distintos ou até mesmo para branches diferentes.

cache:key pode utilizar qualquer variável predefinida.

A chave padrão é configurada para o cache do projeto, o que significa que, por padrão, tudo é compartilhado entre pipelines e jobs desde o GitLab 9.0.

Exemplos de Configuração

Cache por job:

cache:
 key: "$CI_JOB_NAME"
 untracked: true

Cache por branch:

cache:
 key: "$CI_COMMIT_REF_NAME"
 untracked: true

Cache por job e por branch:

cache:
 key: "$CI_JOB_NAME/$CI_COMMIT_REF_NAME"
 untracked: true

Cache por branch e por estágio:

cache:
 key: "$CI_JOB_STAGE/$CI_COMMIT_REF_NAME"
 untracked: true

Se estiver usando o Windows Batch para executar scripts, substitua $ por %:

cache:
 key: "%CI_JOB_STAGE%/%CI_COMMIT_REF_NAME%"
 untracked: true

Jobs

O arquivo .gitlab-ci.yml permite a especificação de um número ilimitado de jobs. Cada job deve ter um nome único e não pode ser uma das palavras-chave reservadas mencionadas anteriormente. Um job é definido por um conjunto de parâmetros que controlam seu comportamento.

nome_do_job:
 script:
   - rake spec
   - coverage
 stage: test
 only:
   - master
 except:
   - develop
 tags:
   - ruby
   - postgres
 allow_failure: true

Palavra-chave	Obrigatório	Descrição
script	Sim	Comandos ou scripts a serem executados pelo Runner.
image	Não	Imagem Docker a ser utilizada. Consulte a documentação de uso de imagens Docker.
services	Não	Serviços Docker a serem utilizados. Consulte a documentação de uso de imagens Docker.
stage	Não	Define o estágio do job (padrão: test).
type	Não	Alias para stage (descontinuado).
variables	Não	Define variáveis em nível de job.
only	Não	Define uma lista de branches Git para os quais o job será executado.
except	Não	Define uma lista de branches Git para os quais o job não será executado.
tags	Não	Define uma lista de tags para selecionar Runners específicos para executar o job (os Runners também devem ter essas tags configuradas).
allow_failure	Não	Permite que o job falhe sem afetar o status geral do commit.
when	Não	Define quando o job deve ser iniciado. Valores possíveis: on_success, on_failure, always ou manual.
dependencies	Não	Define as dependências de artefatos entre jobs.
cache	Não	Define a lista de arquivos a serem cacheados entre execuções.
before_script	Não	Sobrescreve os comandos before_script globais para este job específico.
after_script	Não	Sobrescreve os comandos after_script globais para este job específico.
environment	Não	Define o nome do ambiente para o qual este job realiza o deploy.
coverage	Não	Define as configurações de cobertura de código para um determinado job.

script

script é o script YAML que o Runner executará. Por exemplo:

job:
 script: "bundle exec rspec"

Este parâmetro também pode ser um array contendo múltiplos comandos:

job:
 script:
   - uname -a
   - bundle exec rspec

Em alguns casos, os comandos em script podem precisar ser envolvidos por aspas simples ou duplas. Por exemplo, quando o comando contém dois pontos (:), o script deve ser envolvido por aspas duplas para que o analisador YAML o interprete corretamente como uma string e não como um par chave-valor (key:value). Tenha cuidado ao usar caracteres especiais como: :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !.

stage

stage permite que um conjunto de jobs pertença a diferentes estágios. Jobs no mesmo stage são executados em parallel (paralelo). Consulte stages para mais detalhes sobre seu uso.

only e except

only e except são parâmetros usados para restringir a construção de jobs com base em políticas de branch:

1. only define em quais branches e tags de um projeto Git um job será executado.
2. except define em quais branches e tags de um projeto Git um job não será executado.

As regras de uso para estratégias de refs são:

• only e except podem ser usados simultaneamente. Se ambos estiverem presentes em uma configuração de job, only terá precedência e except será ignorado (conforme inferido do exemplo abaixo).
• only e except podem usar expressões regulares.
• only e except permitem o uso de palavras-chave especiais: branches, tags e triggers.
• only e except permitem especificar um repositório, mas apenas para jobs executados no repositório pai, não em forks (consulte o Exemplo 3).

No exemplo abaixo, o job só será executado em refs que começam com issue-, enquanto o que está definido em except será ignorado.

job:
 # usa regexp
 only:
   - /^issue-.*$/
 # usa palavra-chave especial
 except:
   - branches

No exemplo a seguir, o job só será executado em refs que são tags, ou quando explicitamente solicitado por um gatilho de API.

job:
 # usa palavras-chave especiais
 only:
   - tags
   - triggers

O caminho do repositório só pode ser usado para jobs executados no repositório pai, não em forks:

job:
 only:
   - branches@gitlab-org/gitlab-ce
 except:
   - master@gitlab-org/gitlab-ce

O exemplo acima executará o job para todos os branches, exceto para o branch master.

Variáveis de Job

Variáveis de job podem ser definidas usando a palavra-chave variables dentro de um job. O funcionamento é semelhante ao de variáveis globais, mas permite a configuração de variáveis específicas para o job.

Quando a palavra-chave variables em nível de job é definida, ela substitui as variáveis globais do YAML e as predefinidas para aquele job. Para desativar variáveis globais, pode-se definir um array vazio no job:

nome_do_job:
 variables: []

A prioridade das variáveis de job pode ser consultada na documentação de variáveis.

tags

tags permite selecionar Runners específicos de todos os Runners disponíveis para executar jobs. Ao registrar um Runner, é possível definir tags para ele, como ruby, postgres, development.

tags pode ser usado para especificar Runners particulares para executar jobs:

job:
 tags:
   - ruby
   - postgres

Neste exemplo, o Runner que executar este job deve ter as tags ruby e postgres configuradas.

allow_failure

allow_failure pode ser usado quando se deseja que a falha de um job não afete os componentes subsequentes do CI. Jobs que falham com esta opção habilitada não impactam o status geral do commit.

Quando allow_failure está habilitado, o pipeline inteiro é considerado bem-sucedido (verde), mas uma mensagem como "CI build passed with warnings" será exibida no merge request, commit ou página do job. Isso indica que um job opcional falhou, mas outras ações (manuais) podem ser necessárias.

No exemplo a seguir, job1 e job2 serão executados em paralelo. Se job1 falhar, isso não afetará o próximo estágio, pois allow_failure: true está configurado:

job1:
 stage: test
 script:
 - executar_script_que_vai_falhar
 allow_failure: true

job2:
 stage: test
 script:
 - executar_script_que_vai_ter_sucesso

job3:
 stage: deploy
 script:
 - deploy_para_staging

when

when é usado para implementar jobs que devem ser executados em caso de falha ou independentemente do status de falha.

when pode aceitar os seguintes valores:

1. on_success – Executa apenas se todos os jobs dos estágios anteriores forem bem-sucedidos. Este é o valor padrão.
2. on_failure – Executa se qualquer job nos estágios anteriores falhar.
3. always – Executa independentemente do status dos jobs nos estágios anteriores.
4. manual – Execução manual (adicionado no GitLab 8.10). Consulte a documentação sobre ações manuais.

Exemplo:

stages:
- build
- cleanup_build
- test
- deploy
- cleanup

build_job:
 stage: build
 script:
 - make build

cleanup_build_job:
 stage: cleanup_build
 script:
 - limpar_build_em_caso_de_falha
 when: on_failure

test_job:
 stage: test
 script:
 - make test

deploy_job:
 stage: deploy
 script:
 - make deploy
 when: manual

cleanup_job:
 stage: cleanup
 script:
 - limpar_apos_jobs
 when: always

Explicação dos scripts:

1. cleanup_build_job só será executado se build_job falhar.
2. cleanup_job será executado quer o job anterior tenha falhado ou tido sucesso.
3. deploy_job pode ser executado manualmente a partir da interface do GitLab.

Ações Manuais

Introduzidas no GitLab 8.10 (e em versões subsequentes com melhorias como parada manual e proteção). Ações manuais são um tipo especial de job que não são executadas automaticamente; elas precisam ser iniciadas por um usuário. Elas podem ser iniciadas a partir das visualizações de pipeline, build, ambiente e deploy.

Deploy para o ambiente de produção é um bom exemplo de ação manual.

Para saber mais, consulte a documentação de ambientes.

Ações manuais podem ser opcionais ou bloqueantes. Em um estágio onde uma ação manual é definida, ela interromperá a execução automática dos jobs nesse estágio. A execução do pipeline é retomada quando alguém clica no botão "play" para iniciar o job manual.

Pipelines bloqueados por ações manuais, mesmo que o status geral seja "sucesso", não podem ser mesclados (merged). Pipelines bloqueados também possuem um status especial: manual.

Ações manuais não são bloqueantes por padrão. Para que uma ação manual seja bloqueante, é necessário configurar allow_failure:false no arquivo .gitlab-ci.yml.

Ações manuais opcionais têm allow_failure:true por padrão.

O status de ações manuais opcionais não afeta o status geral do pipeline.

Ações manuais são consideradas operações de escrita, portanto, o usuário que as aciona deve ter permissão para modificar os branches protegidos. Em outras palavras, para acionar uma ação manual em um pipeline em execução para um branch específico, o usuário deve ter permissão para fazer push nesse branch.

environment

Introduzido no GitLab 8.9. Para mais informações e exemplos sobre ambientes, consulte a documentação de ambientes.

environment é usado para definir em qual ambiente um job realiza o deploy. Se um environment for especificado e um ambiente com esse nome ainda não existir, um novo ambiente será criado automaticamente.

Na forma mais simples, a palavra-chave ambiente pode ser definida como:

deploy to production:
 stage: deploy
 script: git push production HEAD:master
 environment:
   name: production

Neste exemplo, o job deploy to production realizará o deploy no ambiente production.

environment:name

Introduzido no GitLab 8.11. Antes desta versão, o nome do ambiente era definido como environment:production. A prática recomendada agora é usar a palavra-chave name.

O nome do environment pode conter:

• Letras
• Números
• Espaços
• Hifens (-)
• Underscores (_)
• Barras (/)
• Símbolos de cifrão ($)
• Chaves ({, })

Nomes comuns incluem qa, staging e production, mas você pode usar qualquer nome que se encaixe no seu fluxo de trabalho.

Além de definir o nome diretamente após a palavra-chave environment, você também pode definir o nome do ambiente separadamente usando a palavra-chave name dentro de environment:

deploy to production:
 stage: deploy
 script: git push production HEAD:master
 environment:
   name: production

environment:url

Introduzido no GitLab 8.11. Antes desta versão, a URL só podia ser adicionada na interface do GitLab. A forma recomendada agora é defini-la em .gitlab-ci.yml.

Este é um valor opcional que será exibido como um botão, permitindo navegar até a URL configurada.

No exemplo a seguir, se o job for concluído com sucesso, um botão será criado na página de ambientes/deployments apontando para https://prod.example.com.

deploy to production:
 stage: deploy
 script: git push production HEAD:master
 environment:
   name: production
   url: https://prod.example.com

environment:on_stop

Introduzido no GitLab 8.13. A partir do GitLab 8.14, quando uma operação de parada é definida em um environment, o GitLab aciona automaticamente essa operação de parada quando o branch associado é excluído.

É possível parar (desativar) ambientes definindo a palavra-chave on_stop dentro de environment. Isso define um job diferente que será responsável por parar o ambiente.

Consulte o módulo environment:action para um exemplo.

environment:action

Introduzido no GitLab 8.13. action é usado em conjunto com on_stop para definir um job que para um ambiente.

Exemplo:

review_app:
 stage: deploy
 script: make deploy-app
 environment:
   name: review
   on_stop: stop_review_app

stop_review_app:
 stage: deploy
 script: make delete-app
 when: manual
 environment:
   name: review
   action: stop

No exemplo acima, definimos o job review_app para fazer deploy no ambiente review. Também definimos um novo job stop_review_app em on_stop. Uma vez que o job review_app seja concluído com sucesso, ele acionará o job stop_review_app, que está definido com when: manual. Neste caso, a ação manual precisará ser permitida na interface web do GitLab.

O job stop_review_app precisa ter as seguintes palavras-chave definidas:

• when – especifica quando o job deve ser executado.
• environment:name – o nome do ambiente a ser parado.
• environment:action – a ação a ser realizada (stop).
• stage – deve ser o mesmo estágio de review_app para que a parada automática ocorra quando o branch for excluído.

Ambientes Dinâmicos

Introduzido no GitLab 8.12 (requer GitLab Runner 1.6). A partir do GitLab 8.15, a variável $CI_ENVIRONMENT_SLUG está disponível.

environment também pode ser um objeto de configuração contendo name e url. Esses parâmetros podem usar quaisquer variáveis de CI (incluindo predefinidas, seguras e definidas em .gitlab-ci.yml).

Exemplo:

deploy as review app:
 stage: deploy
 script: make deploy
 environment:
   name: review/$CI_COMMIT_REF_NAME
   url: https://$CI_ENVIRONMENT_SLUG.example.com/

Quando $CI_COMMIT_REF_NAME é definido como uma variável de ambiente pelo Runner, o job deploy as review app será associado a um ambiente criado dinamicamente: review/$CI_COMMIT_REF_NAME. A variável $CI_ENVIRONMENT_SLUG é gerada com base no nome do ambiente, formando URLs completas. Neste caso, se o job deploy as review app estiver rodando no branch chamado pow, o ambiente poderá ser acessado através da URL https://review-pw.example.com/.

Isso pressupõe que o servidor subjacente que hospeda o aplicativo esteja corretamente configurado.

Uma prática comum é criar ambientes dinâmicos para branches e usá-los como Review Apps. Um exemplo simples de uso de Review Apps pode ser encontrado em gitlab.com/gitlab-org/gitlab-examples.

Continue lendo: Guia Detalhado do Arquivo de Configuração do GitLab CI (.gitlab-ci.yml) (Parte 2)