Utilitários de Pipeline CI/CD BotCity¶

A plataforma BotCity tem suporte nativo ao GitHub Actions por meio do BotCity Actions - Bots.

Para as demais plataformas de CI/CD, você pode usar os scripts Bash descritos nesta página.

Exemplos de pipeline por plataforma

Confira os exemplos de pipeline para GitHub Actions, Azure Pipelines, Woodpecker CI, Bitbucket Pipelines, GitLab CI e Jenkins.

Script de Gerenciamento de Bots¶

O bot.sh é um script Bash que executa as tarefas mais comuns de gerenciamento de bots (deploy, update e release) por meio da API do BotCity Orquestrador.

Com ele, você gerencia seus bots direto do pipeline CI/CD, usando uma interface de linha de comando.

Funcionalidades¶

Deploy: faz o upload e a implantação de uma nova versão de um bot.
Update: atualiza a versão de um bot existente.
Release: libera uma versão de um bot no BotCity Orquestrador.

Requisitos¶

cURL: usado para enviar as requisições HTTP.
Variáveis de ambiente: defina as seguintes variáveis para autenticação:
- SERVER: URL do servidor da API do BotCity Orquestrador.
- LOGIN: seu login na API do BotCity Orquestrador.
- KEY: sua chave da API do BotCity Orquestrador.

Onde encontrar o login e a chave da API

Seu login e sua chave da API do Orquestrador ficam no menu Ambiente do Desenvolvedor. Saiba mais em Ambiente do Desenvolvedor.

Configurar os Secrets do Repositório¶

Antes de executar o bot.sh no pipeline, configure SERVER, LOGIN e KEY como secrets ou variáveis protegidas no seu repositório.

Não exponha credenciais no pipeline

Nunca insira credenciais diretamente no código-fonte do pipeline. Use sempre o mecanismo de secrets da sua plataforma.

GitHub Actions¶

Acesse Settings > Secrets and variables > Actions no repositório.
Clique em New repository secret e cadastre os três valores:

Secret Descrição

SERVER URL da API do BotCity Orquestrador

LOGIN Seu login da API

KEY Sua chave da API
No workflow, exponha os secrets como variáveis de ambiente no step que executa o script:

- name: Deploy bot
  env:
    SERVER: ${{ secrets.SERVER }}
    LOGIN: ${{ secrets.LOGIN }}
    KEY: ${{ secrets.KEY }}
  run: ./bot.sh deploy -version "1.0.0" -botFile "bot.zip" -botId "MyBotId" -type "python"

Saiba mais em Using secrets in GitHub Actions.

GitLab CI¶

Acesse Settings > CI/CD > Variables no projeto.
Adicione SERVER, LOGIN e KEY. Marque a opção Masked em cada uma para que os valores não apareçam nos logs.
As variáveis ficam disponíveis automaticamente em todos os jobs do pipeline:

deploy-bot:
  script:
    - ./bot.sh deploy -version "1.0.0" -botFile "bot.zip" -botId "MyBotId" -type "python"

Saiba mais em GitLab CI/CD variables.

Azure Pipelines¶

Acesse Pipelines > Library e crie um Variable Group com os três valores. Clique no ícone de cadeado de cada variável para marcá-la como secret.
Vincule o variable group ao pipeline e referencie as variáveis no step:

variables:
  - group: botcity-credentials

steps:
  - script: ./bot.sh deploy -version "1.0.0" -botFile "bot.zip" -botId "MyBotId" -type "python"
    env:
      SERVER: $(SERVER)
      LOGIN: $(LOGIN)
      KEY: $(KEY)
    displayName: "Deploy bot"

Saiba mais em Variable groups no Azure Pipelines.

Woodpecker CI¶

Acesse Settings > Secrets do repositório e adicione SERVER, LOGIN e KEY.
Referencie os secrets no step do pipeline:

steps:
  deploy:
    image: alpine
    commands:
      - ./bot.sh deploy -version "1.0.0" -botFile "bot.zip" -botId "MyBotId" -type "python"
    secrets:
      - source: SERVER
        target: SERVER
      - source: LOGIN
        target: LOGIN
      - source: KEY
        target: KEY

Saiba mais em Secrets no Woodpecker CI.

Bitbucket Pipelines¶

Acesse Repository settings > Repository variables e adicione SERVER, LOGIN e KEY. Marque a opção Secured em cada uma para mascarar os valores nos logs.
As variáveis ficam disponíveis automaticamente em todos os steps:

pipelines:
  default:
    - step:
        script:
          - ./bot.sh deploy -version "1.0.0" -botFile "bot.zip" -botId "MyBotId" -type "python"

Saiba mais em Variables and secrets no Bitbucket Pipelines.

Jenkins¶

Acesse Manage Jenkins > Credentials e adicione as três credenciais como Secret text. Anote o ID de cada uma.
No Jenkinsfile, exponha as credenciais com withCredentials:

withCredentials([
  string(credentialsId: 'botcity-server', variable: 'SERVER'),
  string(credentialsId: 'botcity-login', variable: 'LOGIN'),
  string(credentialsId: 'botcity-key', variable: 'KEY')
]) {
  sh './bot.sh deploy -version "1.0.0" -botFile "bot.zip" -botId "MyBotId" -type "python"'
}

Saiba mais em Using credentials no Jenkins.

Usar o Script¶

O script tem três subcomandos: deploy, update e release.

Fazer o Deploy de um Bot¶

Use o subcomando deploy para fazer o upload e a implantação do bot no BotCity Orquestrador.

Parâmetros:

-version: versão do bot.
-botFile: caminho para o arquivo do bot.
-botId: identificador único do bot.
-type: tecnologia do bot (por exemplo, python ou java).
-repository (opcional): rótulo do repositório. Se não for informado, o padrão é DEFAULT.

./bot.sh deploy -version "1.0.0" -botFile "/caminho/para/bot.zip" -botId "MyBotId" -type "python" -repository "DEFAULT"

Atualizar um Bot¶

Use o subcomando update para atualizar a versão de um bot no BotCity Orquestrador.

Parâmetros:

-version: versão do bot.
-botFile: caminho para o arquivo do bot.
-botId: identificador único do bot.

./bot.sh update -version "1.0.0" -botFile "/caminho/para/bot.zip" -botId "MyBotId"

Fazer o Release de um Bot¶

Use o subcomando release para liberar uma versão do bot. Esse subcomando precisa apenas do ID do bot e da versão.

Parâmetros:

-version: versão do bot.
-botId: identificador único do bot.

./bot.sh release -version "1.0.0" -botId "MyBotId"

Exemplos de Comandos¶

Exemplo de Deploy¶

./bot.sh deploy -version "1.2.0" -botFile "/home/usuario/bot.zip" -botId "MeuBotLegal" -type "python" -repository "ProductionRepo"

Exemplo de Atualização¶

./bot.sh update -version "1.2.0" -botFile "/home/usuario/bot_update.zip" -botId "MeuBotLegal"

Exemplo de Release¶

./bot.sh release -version "1.2.0" -botId "MeuBotLegal"

Tratamento de Erros¶

Parâmetros obrigatórios ausentes: o script exibe uma mensagem de uso e é encerrado.
Falha na requisição à API (código de status diferente de 200): o script exibe uma mensagem de erro com os detalhes.

Contribuir com o Projeto¶

Para enviar issues, abrir pull requests ou consultar a licença, acesse o repositório cicd-pipeline-utils no GitHub.

Secret	Descrição
`SERVER`	URL da API do BotCity Orquestrador
`LOGIN`	Seu login da API
`KEY`	Sua chave da API