CLI Integrations

Apply gamification to CI/CD, documentation and more

The CLI tool integrates better with any CI/CD system that uses Docker images to trigger pipelines: Github, GitLab, Jenkins, etc.

In case you don’t have an automated system, you may still use the Quboo CLI integration or the API integration and manually trigger the score. Anyway, it’s better to have this automated, so keep reading to check what the possibilities are.

Instructions per tool

We keep updating the docs to include specific instructions for the most common CI/CD systems. Follow the sections below if you use any of these tools. Otherwise, you can also quickly set up yours by reading the Full CLI Reference in this document.

Gitlab

GitLab has an integrated functionality called GitLab CI/CD where you can define Pipelines as code in your repository in a .gilab-ci.yml file.

Adding Quboo to GitLab Pipelines

To integrate Quboo CLI in your pipeline, you only need to add a stage and use our Docker image. In the example below, the block score sends the points to Quboo.

Gamification with Quboo and Gitlab
Add gamification to your GitLab pipelines
stages:
  - build
  - deploy
  - score

build:
  stage: build
  # ...

deploy:
  stage: deploy
  # ...
  only:
    - master

score:
  image: mechero/quboo-cli:latest
  dependencies: []
  stage: score
  script:
    - quboo release "Quboo Backend Release"
  only:
    - master

To make this work, you have to set up two environment variables with your Quboo’s access and secret keys. These are set in Gitlab at your project or group level (depending on whether you want to set them globally or not), Settings -> CI / CD -> Variables. You need to add QUBOO_ACCESS_KEY and QUBOO_SECRET_KEY. The values are in your Quboo admin account, under the Settings section.

Quboo Access and Secret Keys in variables
Add Quboo access and secret keys

As you see in the script, there is no reference to the player identifier there. The player is, by default, the last committer’s username. If you want to override it, you can do that by setting a value manually to the environment variable QUBOO_PLAYER_USERNAME. Check the Full CLI reference in this same page for all the details.

Gamifying other processes with GitLab

Remember that you can also use the CLI or the Score API to create your own game and give score for other actions such as contributing to documentation.

CircleCI

Similar to GitLab, the Quboo CLI script includes support for CircleCI.

Adding Quboo to CircleCI pipelines

You can simply add a new step in your deployment pipelines in CircleCI and assign score to whoever triggered the pipeline.

Quboo Gamification with CircleCI
Add gamification to your CircleCI pipelines

In the Quboo example repository there is a script that demonstrates how you can set this up in your pipeline.

version: 2.1
jobs:
  build:
    docker:
      - image: maven:3.6-jdk-11
    steps:
      - checkout
      - run:
          command: |
            mvn clean package
  release:
    docker:
      - image: alpine:3.7
    steps:
      - checkout
      - run:
          command: |
            echo '^^^Not really releasing...^^^'
  score:
    docker:
      - image: mechero/quboo-cli:latest
    steps:
      - checkout
      - run:
          command: |
            quboo release "Circle CI Release example"
workflows:
  version: 2
  build_release_score:
    jobs:
      - build
      - release:
          requires:
            - build
          filters:
            branches:
              only: master
      - score:
          requires:
            - release
          filters:
            branches:
              only: master

As you see in the script, there is no reference to the player identifier there. The player is, by default, the last committer’s username. If you want to override it, this is possible by setting a value manually to the environment variable QUBOO_PLAYER_USERNAME. Check the Full CLI reference in this same page for all the details.

Gamifying other processes with CircleCI

Remember that you can also use the CLI or the Score API to create your own game and give score for other actions such as contributing to documentation.

Full CLI Reference

In case you want to integrate with other CI/CD tools, or you want to override the way it works, you can use these instructions:

  1. Make sure your CI/CD tool loads your access and secret keys as the environment variables QUBOO_ACCESS_KEY and QUBOO_SECRET_KEY.
  2. Set the environment variable QUBOO_PLAYER_USERNAME to the player’s login that you want to assign points to. Note: if you are also playing the Sonar game mode, ideally you use the same login identifier. If you prefer to use the git username, you can leave this variable unset and set QUBOO_CONFIG_ALWAYS_USE_GIT to true.
  3. Use the environment variable QUBOO_UNIQUE_ID to set a unique value for the process you want to reward the player for. In case you leave this variable unset, the last git shortened hash will be used as an unique identifier. If the same process (e.g. a specific release) runs twice for any reason, the player will get the points only once. This unique identifier from your side prevents players from cheating by running pipelines more than once.
  4. Take the docker image mechero/quboo-cli:latest (or a specific version to avoid potentially breaking changes) as your base image for the pipeline step and run the script with a given command and parameters. See below for the list of commands.

List of commands

quboo release "description"

Gives score to the player for a ‘release’ action. The points are set to a predefined value. You can use the description to specify the name of the action for which the player is getting score (e.g. “Daily Release” or “Billing service release”).

quboo doc "description"

Same as for the release, but in this case for the ‘doc’ action. The points are also predefined.

quboo 100 "description"

In case you want to decide by yourself how many points the player wins, you can run this command and specify the score instead of passing the action name. Then, you can use the description to clarify the reason. As an advantage, you can create a smarter way of assigning points (e.g. based on the time to release). On the other hand, some Quboo badges that are based on specific action types will not work with these commands.

Customizing the CLI tool

The quboo script’s source code is available in GitHub. You can have a look if you’re curious about how it works but you can also fork the repository and create your own Docker image if you want to adapt it to your own CI/CD system. Not a fan of java? Then better start from scratch.

We also welcome people who want to extend the CLI tool and add compatibility with other tools. Just check with us via a new issue in GitHub.


Slack Worfklows
Use Case Examples