Pmbot works similarly to how a developer would update the dependencies of a Git repository. The main difference is that the process of updating the dependencies, changing package versions, etc, is all done in your CI. We needed a place to make that happen, and your CI was the perfect place: it already has all the features needed such as secret masking, environment variables, docker containers, workspace directory management, cache management, etc, so we decided not to reinvent the wheel. All we needed was a way to trigger specific jobs in your CI configuration file, and fortunately for us, this is possible via most CI platform APIs.

So, in order for you to understand how an update happens, we'll take a simplified example (we're skipping Pmbot installation, core concepts and project setup as all of this is available in our documentation and as we will be publishing specific articles and video tutorials over the next few weeks, stay tuned !).

Say we have a dummy (great name, isn't it ?) Git repository, hosted on a self-hosted Gitlab, which we have of course configured CI for using a .gitlab-ci.yml:

stages:
  - update
  - test
  # must be the last stage !
  - notify

variables:
  PMBOT_URL: {{PMBOT_URL}}
  PMBOT_PROJECT_ID: {{PMBOT_PROJECT_ID}}
  # !!!!! place this in a secret CI/CD variable !!!!!
  # https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui
  PROJECT_TOKEN: {{PROJECT_TOKEN}}

update:
  stage: update
  image: pmbot/bot
  # run the update job only when variable environment $PMBOT is "true"
  only:
    variables:
      - $PMBOT == "true"
  script:
    # install your dependencies
    - npm ci
    # run the update
    - pmbot update --disable-host-key-verification

# your existing build/test jobs
test:
  stage: test
  image: node:12-alpine
  # skip this job when running the update job
  except:
    variables:
      - $PMBOT == "true"
  script:
    - npm ci
    - npm test

# notify pmbot of pipeline success
on-success:
  stage: notify
  image: pmbot/bot
  when: on_success
  script:
    - pmbot notify --success

# notify pmbot of pipeline success
on-failure:
  stage: notify
  image: pmbot/bot
  when: on_failure
  script:
    - pmbot notify

The test  job is our standard pipeline, that we use to make sure our app works as expected. That's your chai, jest, junit ... We could have more jobs like build, lint, etc, but for this example, let's keep things simple.

The update  job runs the pmbot CLI, distributed in our official Docker image or as an Npm package which you can embed in custom Docker images.

The important part in the above .gitlab-ci.yml  is the $PMBOT == "true"  check which allows us to enable only the update  job when we trigger Gitlab CI with variable PMBOT set to true.

The pmbot CLI takes care of reading your .pmbot.yml file for which a good starter version for updating your Npm dependencies looks like this:

version: "1"
packageManagers:
  - packageManager:
      name: npm
    actions:
      - name: auto-merge
        on:
          - success
          - partial
      - name: slack
        config:
          url: https://hooks.slack.com/services/abcd/abcd/123
        on:
          - failure

Let's assume that we've already installed Pmbot, connected Gitlab to it and scheduled daily updates for dummy. Now, every day at midnight UTC, the magic happens:

  • Pmbot's backend tells Gitlab to run the update job declared in the .gitlab-ci.yml of dummy
  • Gitlab runs the update job, which runs the pmbot CLI and list all dependencies that need to be updated. Say that its finds that chalk needs to be updated from 1.0.0 to 1.0.1 and winston needs to be updated from 2.0.1 to 3.0.0. The pmbot CLI directly updates chalk to 1.0.1, commits and pushes to dummy on a new branch `update/npm`.
  • As Gitlab CI sees a new commit in dummy, it automatically triggers a new CI pipeline, which will run all jobs of .gitlab-ci.yml BUT update. In this case, it runs the build job.
  • Pmbot's backend listens to the output of your Gitlab CI pipelines. When it sees that the pipeline has passed, it resumes the update by telling Gitlab to run the `update` job again. This time, the pmbot CLI updates winston to version 3.0.0, commits and pushes again.
  • The same process as above is repeated. Pmbot listens to the pipeline status and resumes the update when the pipeline has finished. If a pipeline ever fails, the pmbot CLI reverts the previous commit and continues with the next dependencies to update.
  • When all dependencies have been updated, our CLI executes the actions configured in `.pmbot.yml`. In this case, since the update was successful, it automatically merges the changes to the branch from which the update started, using the auto-merge plugin.

And that's it ! The next morning, you get to work, your dependencies are up to date. And when something fails to update, you'll get notified via a Slack message, thanks to the slack plugin. There are a lot more plugins which you can find in our documentation, but best of all, you can create your own plugins. We greatly encourage you to do so and to let us know about it so we can add your plugins to our documentation !

If you want to view the above process summarized in one animation, here you go:

Animation of how Pmbot works

The above scenario uses Gitlab as git provider, Gitlab CI as CI provider and Npm as package manager, but Pmbot is compatible with many more platforms and package managers:

Git platforms

  • Gitlab.com
  • Github
  • coming soon: Bitbucket, Gitea, Cogs...

CI platforms

  • Gitlab CI
  • Drone CI

coming soon: Github actions, Travis CI, Circle CI...

Package managers

  • Npm
  • Go
  • Maven
  • coming soon: Docker, Bundler, Composer..