Using GitHub Actions to update your Bot¶

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

For more information, visit our repository.

To read more about GitHub Actions, visit the official documentation.

Configuring the project¶

First, you need to create a folder called .github in your project, and inside create another folder called workflows.

The folder structure should look like this:

.
└── .github
  └── workflows
...

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

Create your first `workflow`¶

The first workflow we will create is simple when a push happens in the main branch, we will trigger an action to update the bot in Maestro.

Important

In this case, there must be a `Bot` previously created in Maestro.
To read more about `Bots`, visit the [documentation](https://documentation.botcity.dev/maestro/features/bots){target="_blank"} page.

Capturing the "push" event in `main`¶

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

At the beginning of this file, add the following lines:

name: Update the latest version of Bot in Maestro.

on:
  push:
    branches:
      - main

Generating the Bot.¶

At this stage, we only need one prerequisite:

A .sh file to generate the Bot.

With this file in the project, we can proceed with the example.

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@v3
      # Implemented executable permission to `.sh`
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute to build.
      - 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@v3
      # Implemented executable permission to `.sh`
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute to build.
      - 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@v3
      # Implemented executable permission to `.sh`
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute to build.
      - 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@v3
      # Implemented executable permission to `.sh`
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute to build.
      - name: Execute to build.
        run: ./build.sh

Important

Your `Bot` may need more steps to be performed. It will depend on each project.

Using an `action`¶

After executing what is needed to generate the Bot, it's time to use the action to update in Maestro.

PythonJavaJavascriptTypescript

      - name: Using a Botcity action.
        # Using the v1.0.0 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.0
        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.0 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.0
        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.0 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.0
        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.0 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.0
        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 }}

Warning

Always configure your credentials in repository secrets for security reasons. It is not recommended to pass this information directly. To learn more about secrets, visit the documentation.

Run push in the main, and the result will be this:

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@v3
      # Implemented executable permission to `.sh`
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute to build.
      - name: Execute to build.
        run: ./build.sh
      - name: Using a Botcity action.
        # Using the v1.0.0 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.0
        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@v3
      # Implemented executable permission to `.sh`
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute to build.
      - name: Execute to build.
        run: ./build.sh
      - name: Using a Botcity action.
        # Using the v1.0.0 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.0
        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@v3
      # Implemented executable permission to `.sh`
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute to build.
      - name: Execute to build.
        run: ./build.sh
      - name: Using a Botcity action.
        # Using the v1.0.0 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.0
        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@v3
      # Implemented executable permission to `.sh`
      - name: Get permission to build.
        run: chmod +x build.sh
      # Execute to build.
      - name: Execute to build.
        run: ./build.sh
      - name: Using a Botcity action.
        # Using the v1.0.0 version of botcity-action-bots
        uses: botcity-dev/botcity-action-bots@v1.0.0
        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 }}

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

Here things start to get more interesting. There may be a thousand ways to do it, but what will be demonstrated will be an example.

Let's clarify what we want with this workflow:

A Release will have to be made on GitHub.
With Release, there must be the creation of a tag.
Deploy/Release will run on Maestro.

To know how to create a release.

Capturing release publishing event¶

name: Deploy and Release in from GitHub release

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

Important

There are other interesting events that GitHub triggers that can help you. To learn more, visit the documentation.

Building your bot¶

PythonJavaJavascriptTypescript

jobs:
  deploy-and-release:
    name: Deploy and release in BotCity.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Get permission to build.
        run: chmod +x build.sh
      - name: Execute to build.
        run: ./build.sh

jobs:
  deploy-and-release:
    name: Deploy and release in BotCity.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-java@v3
      - uses: actions/checkout@v3
      - name: Get permission to build.
        run: chmod +x build.sh
      - name: Execute to build.
        run: ./build.sh

jobs:
  deploy-and-release:
    name: Deploy and release in BotCity.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Get permission to build.
        run: chmod +x build.sh
      - name: Execute to build.
        run: ./build.sh

jobs:
  deploy-and-release:
    name: Deploy and release in BotCity.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Get permission to build.
        run: chmod +x build.sh
      - name: Execute to build.
        run: ./build.sh

Using the action¶

Important

In this case, it is important to highlight the use of the variable made available by GitHub to make the release version dynamic.

PythonJavaJavascriptTypescript

      - name: Botcity action
        uses: botcity-dev/botcity-action-bots@v1.0.0
        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: Botcity action
        uses: botcity-dev/botcity-action-bots@v1.0.0
        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: Botcity action
        uses: botcity-dev/botcity-action-bots@v1.0.0
        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: Botcity action
        uses: botcity-dev/botcity-action-bots@v1.0.0
        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 }}

Execute publish release and the result will be this:

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@v3
      - 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.0
        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@v3
      - 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.0
        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@v3
      - 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.0
        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@v3
      - 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.0
        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 }}

Using GitHub Actions to update your Bot¶

Configuring the project¶

Create your first workflow¶

Capturing the "push" event in main¶

Generating the Bot.¶

Using an action¶

Full file¶

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

Capturing release publishing event¶

Building your bot¶

Using the action¶

Full file¶

Create your first `workflow`¶

Capturing the "push" event in `main`¶

Using an `action`¶