Skip to content

BotCity CI/CD Pipeline Utilities

The BotCity platform natively supports GitHub Actions through BotCity Actions - Bots.

For other CI/CD platforms, you can use the Bash scripts described on this page.

Pipeline examples by platform

Check out the pipeline examples for GitHub Actions, Azure Pipelines, Woodpecker CI, Bitbucket Pipelines, GitLab CI, and Jenkins.

Bot Management Script

bot.sh is a Bash script that runs the most common bot management tasks (deploy, update, and release) through the BotCity Orchestrator API.

With it, you manage your bots directly from your CI/CD pipeline, using a command-line interface.

Features

  • Deploy: uploads and deploys a new version of a bot.
  • Update: updates the version of an existing bot.
  • Release: releases a bot version in BotCity Orchestrator.

Requirements

  • cURL: used to send the HTTP requests.
  • Environment variables: set the following variables for authentication:
    • SERVER: BotCity Orchestrator API server URL.
    • LOGIN: your BotCity Orchestrator API login.
    • KEY: your BotCity Orchestrator API key.

Where to find your API login and key

Your Orchestrator API login and key are in the Dev. Environment menu. Learn more at Developer Environment.

Configure Repository Secrets

Before running bot.sh in your pipeline, configure SERVER, LOGIN, and KEY as secrets or protected variables in your repository.

Don't expose credentials in your pipeline

Never insert credentials directly into your pipeline source code. Always use your platform's secrets mechanism.

GitHub Actions

  1. Go to Settings > Secrets and variables > Actions in your repository.

  2. Click New repository secret and add the three values:

    Secret Description
    SERVER BotCity Orchestrator API URL
    LOGIN Your API login
    KEY Your API key

  3. In your workflow, expose the secrets as environment variables in the step that runs the 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"

Learn more at Using secrets in GitHub Actions.

GitLab CI

  1. Go to Settings > CI/CD > Variables in your project.
  2. Add SERVER, LOGIN, and KEY. Check the Masked option on each one so the values don't appear in logs.
  3. The variables are automatically available in every pipeline job:
deploy-bot:
  script:
    - ./bot.sh deploy -version "1.0.0" -botFile "bot.zip" -botId "MyBotId" -type "python"

Learn more at GitLab CI/CD variables.

Azure Pipelines

  1. Go to Pipelines > Library and create a Variable Group with the three values. Click the lock icon on each variable to mark it as secret.
  2. Link the variable group to the pipeline and reference the variables in the 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"

Learn more at Variable groups in Azure Pipelines.

Woodpecker CI

  1. Go to your repository's Settings > Secrets and add SERVER, LOGIN, and KEY.
  2. Reference the secrets in the pipeline step:
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

Learn more at Secrets in Woodpecker CI.

Bitbucket Pipelines

  1. Go to Repository settings > Repository variables and add SERVER, LOGIN, and KEY. Check the Secured option on each one to mask the values in logs.
  2. The variables are automatically available in every step:
pipelines:
  default:
    - step:
        script:
          - ./bot.sh deploy -version "1.0.0" -botFile "bot.zip" -botId "MyBotId" -type "python"

Learn more at Variables and secrets in Bitbucket Pipelines.

Jenkins

  1. Go to Manage Jenkins > Credentials and add the three credentials as Secret text. Write down the ID of each one.
  2. In your Jenkinsfile, expose the credentials with 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"'
}

Learn more at Using credentials in Jenkins.

Use the Script

The script has three subcommands: deploy, update, and release.

Deploy a Bot

Use the deploy subcommand to upload and deploy the bot to BotCity Orchestrator.

Parameters:

  • -version: bot version.
  • -botFile: path to the bot file.
  • -botId: bot unique identifier.
  • -type: bot technology (for example, python or java).
  • -repository (optional): repository label. If not provided, defaults to DEFAULT.
./bot.sh deploy -version "1.0.0" -botFile "/path/to/bot.zip" -botId "MyBotId" -type "python" -repository "DEFAULT"

Update a Bot

Use the update subcommand to update the version of a bot in BotCity Orchestrator.

Parameters:

  • -version: bot version.
  • -botFile: path to the bot file.
  • -botId: bot unique identifier.
./bot.sh update -version "1.0.0" -botFile "/path/to/bot.zip" -botId "MyBotId"

Release a Bot

Use the release subcommand to release a bot version. This subcommand only needs the bot ID and the version.

Parameters:

  • -version: bot version.
  • -botId: bot unique identifier.
./bot.sh release -version "1.0.0" -botId "MyBotId"

Command Examples

Deploy Example

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

Update Example

./bot.sh update -version "1.2.0" -botFile "/home/user/bot_update.zip" -botId "MyCoolBot"

Release Example

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

Error Handling

  • Missing required parameters: the script displays a usage message and exits.
  • API request failure (status code other than 200): the script displays an error message with the details.

Contribute to the Project

To submit issues, open pull requests, or check the license, visit the cicd-pipeline-utils repository on GitHub.