Using GitHub Actions to update your Bot¶

With GitHub Actions, it is possible to make automatic updates, deploys, and releases for BotCity Maestro Orchestrator without the need for manual processes.

We will go through a how-to in this section, you can access more information and details in our repository.

If you're not familiar with GitHub Actions, visit the official GitHub documentation.

Configuring the project¶

First you need to create a folder called .github in your project and inside it create another folder called workflows, in this folder will be the .yml files.

The folder structure should look like this:

.
└── .github
  └── workflows
    ├── update_bot.yml
    └── deploy_and_release.yml
...

To read more about writing workflows in GitHub Actions, visit the GitHub documentation.

Create your first `workflow`¶

The first workflow we will create will be to update an existing bot. We will use an event on a specific branch to trigger the update.

We will define:

Event: push
Branch: main
That is, every time there is a push to the main branch, the workflow will be triggered.

Important

In this case, it is necessary to have an Automation previously created in the BotCity Maestro Orchestrator. Suggestion: Perform the first deployment using the Easy Deploy feature.

Capturing the defined event¶

Create a file called update_bot.yml inside the workflows folder.

At the beginning of this file, we will put the name of the workflow and the event we defined, as follows:

name: Update the latest version of the Bot in Maestro Orchestrator.

on:
  push:
    branches:
      - main

Generating the Bot `build`¶

At this stage we need, as a prerequisite, a file called build.sh in the root of the project that contains the commands necessary to compile the Bot.

PythonJavaJavascriptTypescript

jobs:
  update-latest:
    name: Update the latest version bot on BotCity Maestro.
    #  Running the latest version of Ubuntu.
    runs-on: ubuntu-latest
    steps:
      # Checking out the project.
      - uses: actions/checkout@v4
      # Implemented executable permission to build.sh
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute the build script to compile the project
      - name: Execute to build.
        run: ./build.sh

jobs:
  update-latest:
    name: Update the latest version bot on BotCity Maestro.
    #  Running the latest version of Ubuntu.
    runs-on: ubuntu-latest
    steps:
      # Install Java
      - uses: actions/setup-java@v3
      # Checking out the project.
      - uses: actions/checkout@v4
      # Implemented executable permission to build.sh
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute the build script to compile the project
      - name: Execute to build.
        run: ./build.sh

jobs:
  update-latest:
    name: Update the latest version bot on BotCity Maestro.
    #  Running the latest version of Ubuntu.
    runs-on: ubuntu-latest
    steps:
      # Checking out the project.
      - uses: actions/checkout@v4
      # Implemented executable permission to build.sh
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute the build script to compile the project
      - name: Execute to build.
        run: ./build.sh

jobs:
  update-latest:
    name: Update the latest version bot on BotCity Maestro.
    #  Running the latest version of Ubuntu.
    runs-on: ubuntu-latest
    steps:
      # Checking out the project.
      - uses: actions/checkout@v4
      # Implemented executable permission to build.sh
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute the build script to compile the project
      - name: Execute to build.
        run: ./build.sh

Important

The steps described can be adapted for each project, if necessary add more steps within steps.

Using `action`¶

With the previous step completed, let's add the BotCity Action that will update the Bot in the BotCity Maestro Orchestrator.

In this step, it is necessary to configure the environment variables within the repository on GitHub. Let's add the credentials to access the BotCity Maestro Orchestrator: LOGIN, SERVER and KEY. You can find this information in Developer Amb., within the Orchestrator.

Warning

Always configure your credentials in the repository secrets for security reasons. It is not recommended to pass this information directly in the code.

With the secrets ready, still within steps, add the action settings:

PythonJavaJavascriptTypescript

      - name: Using a Botcity action.
        # Using the v1.0.6 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.6
        with:
          # Use the update function.
          update: true
          # Bot Id in Maestro.
          botId: 'example'
          # Technology utilized in bot
          technology: 'python'
          # Path from the root of the project where the generated .zip/.jar will be.
          botPath: './bot.zip'
        env:
          # These secrets must be configured in your repository.
          LOGIN: ${{ secrets.LOGIN }}
          SERVER: ${{ secrets.SERVER }}
          KEY: ${{ secrets.KEY }}

      - name: Using a Botcity action.
        # Using the v1.0.6 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.6
        with:
          # Use the update function.
          update: true
          # Bot Id in Maestro.
          botId: 'example'
          # Technology utilized in bot
          technology: 'java'
          # Path from the root of the project where the generated .zip/.jar will be.
          botPath: './dist/bot-jar-with-dependencies.jar'
        env:
          # These secrets must be configured in your repository.
          LOGIN: ${{ secrets.LOGIN }}
          SERVER: ${{ secrets.SERVER }}
          KEY: ${{ secrets.KEY }}

      - name: Using a Botcity action.
        # Using the v1.0.6 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.6
        with:
          # Use the update function.
          update: true
          # Bot Id in Maestro.
          botId: 'example'
          # Technology utilized in bot
          technology: 'javascript'
          # Path from the root of the project where the generated .zip/.jar will be.
          botPath: './bot.zip'
        env:
          # These secrets must be configured in your repository.
          LOGIN: ${{ secrets.LOGIN }}
          SERVER: ${{ secrets.SERVER }}
          KEY: ${{ secrets.KEY }}

      - name: Using a Botcity action.
        # Using the v1.0.6 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.6
        with:
          # Use the update function.
          update: true
          # Bot Id in Maestro.
          botId: 'example'
          # Technology utilized in bot
          technology: 'typescript'
          # Path from the root of the project where the generated .zip/.jar will be.
          botPath: './bot.zip'
        env:
          # These secrets must be configured in your repository.
          LOGIN: ${{ secrets.LOGIN }}
          SERVER: ${{ secrets.SERVER }}
          KEY: ${{ secrets.KEY }}

Attention

Within with we indicate the parameters to be used, remember to replace the values:

botId: ID of your Bot in the BotCity Maestro Orchestrator.
technology: technology used in the Bot.
botPath: path of the file generated by the build.
version: the version of the Bot.
repositoryLabel: name of the Bot repository.

The parameters are mandatory in the following actions:

deploy: botId, technology, botPath, version, repositoryLabel
uptade: botId, technology, botPath
release: botId, technology, botPath, version

Full file¶

PythonJavaJavascriptTypescript

name: Update the latest version of Bot in Maestro.

on:
  push:
    branches:
      - main
jobs:
  update-latest:
    name: Update the latest version bot on BotCity Maestro.
    # Running the latest version of Ubuntu.
    runs-on: ubuntu-latest
    steps:
      # Checking out the project.
      - uses: actions/checkout@v4
      # Implemented executable permission to build.sh
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute the build script to compile the project
      - name: Execute to build.
        run: ./build.sh
      - name: Using a Botcity action.
        # Using the v1.0.6 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.6
        with:
          # Use the update function.
          update: true
          # Bot Id in Maestro.
          botId: 'example'
          # Technology utilized in bot
          technology: 'python'
          # Path from the root of the project where the generated .zip/.jar will be.
          botPath: './bot.zip'
        env:
          # These secrets must be configured in your repository.
          LOGIN: ${{ secrets.LOGIN }}
          SERVER: ${{ secrets.SERVER }}
          KEY: ${{ secrets.KEY }}

name: Update the latest version of Bot in Maestro.

on:
  push:
    branches:
      - main
jobs:
  update-latest:
    name: Update the latest version bot on BotCity Maestro.
    #  Running the latest version of Ubuntu.
    runs-on: ubuntu-latest
    steps:
      # Install Java
      - uses: actions/setup-java@v3
      # Checking out the project.
      - uses: actions/checkout@v4
      # Implemented executable permission to build.sh
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute the build script to compile the project
      - name: Execute to build.
        run: ./build.sh
      - name: Using a Botcity action.
        # Using the v1.0.6 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.6
        with:
          # Use the update function.
          update: true
          # Bot Id in Maestro.
          botId: 'example'
          # Technology utilized in bot
          technology: 'java'
          # Path from the root of the project where the generated .zip/.jar will be.
          botPath: './dist/bot-jar-with-dependecies.jar'
        env:
          # These secrets must be configured in your repository.
          LOGIN: ${{ secrets.LOGIN }}
          SERVER: ${{ secrets.SERVER }}
          KEY: ${{ secrets.KEY }}

name: Update the latest version of Bot in Maestro.

on:
  push:
    branches:
      - main
jobs:
  update-latest:
    name: Update the latest version bot on BotCity Maestro.
    #  Running the latest version of Ubuntu.
    runs-on: ubuntu-latest
    steps:
      # Checking out the project.
      - uses: actions/checkout@v4
      # Implemented executable permission to build.sh
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute the build script to compile the project
      - name: Execute to build.
        run: ./build.sh
      - name: Using a Botcity action.
        # Using the v1.0.6 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.6
        with:
          # Use the update function.
          update: true
          # Bot Id in Maestro.
          botId: 'example'
          # Technology utilized in bot
          technology: 'javascript'
          # Path from the root of the project where the generated .zip/.jar will be.
          botPath: './bot.zip'
        env:
          # These secrets must be configured in your repository.
          LOGIN: ${{ secrets.LOGIN }}
          SERVER: ${{ secrets.SERVER }}
          KEY: ${{ secrets.KEY }}

name: Update the latest version of Bot in Maestro.

on:
  push:
    branches:
      - main
jobs:
  update-latest:
    name: Update the latest version bot on BotCity Maestro.
    #  Running the latest version of Ubuntu.
    runs-on: ubuntu-latest
    steps:
      # Checking out the project.
      - uses: actions/checkout@v4
      # Implemented executable permission to build.sh
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute the build script to compile the project
      - name: Execute to build.
        run: ./build.sh
      - name: Using a Botcity action.
        # Using the v1.0.6 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.6
        with:
          # Use the update function.
          update: true
          # Bot Id in Maestro.
          botId: 'example'
          # Technology utilized in bot
          technology: 'typescript'
          # Path from the root of the project where the generated .zip/.jar will be.
          botPath: './bot.zip'
        env:
          # These secrets must be configured in your repository.
          LOGIN: ${{ secrets.LOGIN }}
          SERVER: ${{ secrets.SERVER }}
          KEY: ${{ secrets.KEY }}

Result¶

With the file ready, let's trigger the workflow according to the defined event. Execute a push on main and see the result similar to this:

Creating an advanced workflow to deploy and release your Bot.¶

Using GitHub Actions, you can create more advanced workflows to execute the deployment and release of your Bot in the BotCity Maestro Orchestrator. You can configure its triggering from the various events available on GitHub.

As an example, let's create a workflow that will be triggered when a release is published on GitHub.

We will define:

Event: release
Type: [ published ]

Note

To define the Deploy version and the Bot Release in the BotCity Maestro Orchestrator, we will use the Release tag. To understand how to create Releases on GitHub, access the GitHub documentation.

Capturing release publishing event¶

Create a file called deploy_and_release.yml inside the workflows folder.

At the beginning of this file, we will put the name of the workflow and the event we defined, as follows:

name: Deploy and Release in from GitHub release

on:
  # Capturing the release publishing event.
  release:
    types: [ published ]

Generating the Bot `build`¶

Just like previously we need as a prerequisite a file called build.sh in the root of the project.

PythonJavaJavascriptTypescript

jobs:
  deploy-and-release:
    name: Deploy and release in BotCity.
    runs-on: ubuntu-latest
    steps:
      # Checking out the project.
      - uses: actions/checkout@v4
      # Implemented executable permission to build.sh
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute the build script to compile the project
      - name: Execute to build.
        run: ./build.sh

jobs:
  deploy-and-release:
    name: Deploy and release in BotCity.
    runs-on: ubuntu-latest
    steps:
      # Installing Java
      - uses: actions/setup-java@v3
      # Checking out the project.
      - uses: actions/checkout@v4
      # Implemented executable permission to build.sh
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute the build script to compile the project
      - name: Execute to build.
        run: ./build.sh

jobs:
  deploy-and-release:
    name: Deploy and release in BotCity.
    runs-on: ubuntu-latest
    steps:
      # Checking out the project.
      - uses: actions/checkout@v4
      # Implemented executable permission to build.sh
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute the build script to compile the project
      - name: Execute to build.
        run: ./build.sh

jobs:
  deploy-and-release:
    name: Deploy and release in BotCity.
    runs-on: ubuntu-latest
    steps:
      # Checking out the project.
      - uses: actions/checkout@v4
      # Implemented executable permission to build.sh
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute the build script to compile the project
      - name: Execute to build.
        run: ./build.sh

Using `action`¶

In this step, in addition to using the credentials configured in the repository as previously, we will also use GitHub event variables.

The github.event.release.tag_name variable returns the name of the tag used when publishing a release on GitHub.

PythonJavaJavascriptTypescript

      - name: Botcity action
        # Using v1.0.6 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.6
        with:
          # Use deploy and release functions
          deploy: true
          release: true
          # Use tag_name from GitHub release event
          version: ${{ github.event.release.tag_name }}
          botId: 'example'
          technology: 'python'
          botPath: './bot.zip'
        env:
          LOGIN: ${{ secrets.LOGIN }}
          SERVER: ${{ secrets.SERVER }}
          KEY: ${{ secrets.KEY }}

      - name: Botcity action
        # Using v1.0.6 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.6
        with:
          # Use deploy and release functions
          deploy: true
          release: true
          # Use tag_name from GitHub release event
          version: ${{ github.event.release.tag_name }}
          botId: 'example'
          technology: 'java'
          botPath: './dist/bot-jar-with-dependencies.jar'
        env:
          LOGIN: ${{ secrets.LOGIN }}
          SERVER: ${{ secrets.SERVER }}
          KEY: ${{ secrets.KEY }}

      - name: Botcity action
        # Using v1.0.6 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.6
        with:
          # Use deploy and release functions
          deploy: true
          release: true
          # Use tag_name from GitHub release event
          version: ${{ github.event.release.tag_name }}
          botId: 'example'
          technology: 'javascript'
          botPath: './bot.zip'
        env:
          LOGIN: ${{ secrets.LOGIN }}
          SERVER: ${{ secrets.SERVER }}
          KEY: ${{ secrets.KEY }}

      - name: Botcity action
        # Using v1.0.6 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.6
        with:
          # Use deploy and release functions
          deploy: true
          release: true
          # Use tag_name from GitHub release event
          version: ${{ github.event.release.tag_name }}
          botId: 'example'
          technology: 'typescript'
          botPath: './bot.zip'
        env:
          LOGIN: ${{ secrets.LOGIN }}
          SERVER: ${{ secrets.SERVER }}
          KEY: ${{ secrets.KEY }}

Attention

Within with we indicate the parameters to be used, remember to replace the values:

botId: ID of your Bot in the BotCity Maestro Orchestrator.
technology: technology used in the Bot.
botPath: path of the file generated by the build.
version: the version of the Bot.
repositoryLabel: name of the Bot repository.

The parameters are mandatory in the following actions:

deploy: botId, technology, botPath, version, repositoryLabel
uptade: botId, technology, botPath
release: botId, technology, botPath, version

Full file¶

PythonJavaJavascriptTypescript

name: Deploy and Release in from GitHub release

on:
  # Capturing the release publishing event.
  release:
    types: [ published ]

jobs:
  deploy-and-release:
    name: Deploy and release in BotCity.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Get permission to build.
        run: chmod +x build.sh
      - name: Execute to build.
        run: ./build.sh
      - name: Botcity action
        uses: botcity-dev/botcity-action-bots@v1.0.6
        with:
          deploy: true
          release: true
          # Use tag_name to release.
          version: ${{ github.event.release.tag_name }}
          botId: 'example'
          technology: 'python'
          botPath: './bot.zip'
        env:
          LOGIN: ${{ secrets.LOGIN }}
          SERVER: ${{ secrets.SERVER }}
          KEY: ${{ secrets.KEY }}

name: Deploy and Release in from GitHub release

on:
  # Capturing the release publishing event.
  release:
    types: [ published ]

jobs:
  deploy-and-release:
    name: Deploy and release in BotCity.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-java@v3
      - uses: actions/checkout@v4
      - name: Get permission to build.
        run: chmod +x build.sh
      - name: Execute to build.
        run: ./build.sh
      - name: Botcity action
        uses: botcity-dev/botcity-action-bots@v1.0.6
        with:
          deploy: true
          release: true
          # Use tag_name to release.
          version: ${{ github.event.release.tag_name }}
          botId: 'example'
          technology: 'java'
          botPath: './dist/bot-jar-with-dependencies.jar'
        env:
          LOGIN: ${{ secrets.LOGIN }}
          SERVER: ${{ secrets.SERVER }}
          KEY: ${{ secrets.KEY }}

name: Deploy and Release in from GitHub release

on:
  # Capturing the release publishing event.
  release:
    types: [ published ]

jobs:
  deploy-and-release:
    name: Deploy and release in BotCity.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Get permission to build.
        run: chmod +x build.sh
      - name: Execute to build.
        run: ./build.sh
      - name: Botcity action
        uses: botcity-dev/botcity-action-bots@v1.0.6
        with:
          deploy: true
          release: true
          # Use tag_name to release.
          version: ${{ github.event.release.tag_name }}
          botId: 'example'
          technology: 'javascript'
          botPath: './bot.zip'
        env:
          LOGIN: ${{ secrets.LOGIN }}
          SERVER: ${{ secrets.SERVER }}
          KEY: ${{ secrets.KEY }}

name: Deploy and Release in from GitHub release

on:
  # Capturing the release publishing event.
  release:
    types: [ published ]

jobs:
  deploy-and-release:
    name: Deploy and release in BotCity.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Get permission to build.
        run: chmod +x build.sh
      - name: Execute to build.
        run: ./build.sh
      - name: Botcity action
        uses: botcity-dev/botcity-action-bots@v1.0.6
        with:
          deploy: true
          release: true
          # Use tag_name to release.
          version: ${{ github.event.release.tag_name }}
          botId: 'example'
          technology: 'typescript'
          botPath: './bot.zip'
        env:
          LOGIN: ${{ secrets.LOGIN }}
          SERVER: ${{ secrets.SERVER }}
          KEY: ${{ secrets.KEY }}

Result¶

Execute publish release and the result will be this:

BotCity CI/CD Pipeline Utilities¶

This Practical Guide focuses on the use of GitHub Actions, but it is possible to use other technologies through the BotCity CI/CD Pipeline Utilities. Check out the repository for integration examples with GitHub Actions, Azure Pipelines, Woodpecker CI, BitBucket Pipelines, GitLab CI, and Jenkins.

Using GitHub Actions to update your Bot¶

Configuring the project¶

Create your first workflow¶

Capturing the defined event¶

Generating the Bot build¶

Using action¶

Full file¶

Result¶

Creating an advanced workflow to deploy and release your Bot.¶

Capturing release publishing event¶

Generating the Bot build¶

Using action¶

Full file¶

Result¶

BotCity CI/CD Pipeline Utilities¶

Create your first `workflow`¶

Generating the Bot `build`¶

Using `action`¶

Generating the Bot `build`¶

Using `action`¶