Newborn Programming Monsters


    0.8.1 • Public • Published

    Directus Hook Extension: Version Control Changelog

    Node.js CI Build Badge npm version

    This package is a Hook Extension for the CMS Directus that allows you to add entries to a changelog in a version control system. Currently only Bitbucket Server is supported, but it is prepared to be extended to other version control systems (like GitHub or GitLab) in the future.

    Instead of just "blindly" adding each change in the database it relies on a user written changelog entry that summarizes the changes. For that it relies on a singleton collection with (at least) a textarea field in it.

    Why would I want that?

    We (BI X) created this extension because of the way how GatsbyJS with Directus as content source and our build system (OpenDevStack with ods-pipeline) work.
    Our builds are triggered by webhooks that get fired on pushes to our VCS server. For that it relies heavily on the Bitbucket webhooks and its specific content. Recreating them with the Directus webhook functionality would have been a huge effort - and as our build system does not rebuild things if there are no changes (to the codebase / repository) it would also be without any effect.

    Additionally we wanted to see what has changed in a new release - code as well as content.

    That is why we decided to maintain a changelog inside of the VCS that can be updated by Directus. And for that we wrote this extension hook.

    Table of Contents

    How can I use it?

    Set up things in Directus

    1. Create a singleton collection with at least one textarea

    First you create a new collection in your Directus - make sure that the option to treat it as a single object is activated: Screenshot of the collection setup

    Then you add at least one textarea field and make sure that it is requiring content in there to be saved: Screenshot of the textarea setup

    While the above shown is enough we recommend to use the features of Directus to give the content managers more guidance. Below you see our setup where we used the placeholder and the note of the textarea - as well as a readonly-field with an instructional message as default content: Screenshot of a recommended setup

    2. Add the required configuration values to your Directus installation

    The extension uses the configuration mechanism of Directus. So all you have to do is to add the following variables to your preferred configuration location:

    Variable Name Description
    VERSION_CONTROL_CHANGELOG_COLLECTION name of the collection (e.g. vcs_changelog)
    VERSION_CONTROL_CHANGELOG_FIELD_NAME name of the field in the collection (e.g. changes_made)
    VERSION_CONTROL_CHANGELOG_VCS Has to be bitbucket for now
    VERSION_CONTROL_CHANGELOG_BITBUCKET_USER the user of the Bitbucket VCS server
    VERSION_CONTROL_CHANGELOG_BITBUCKET_PASSWORD the password for the user above
    VERSION_CONTROL_CHANGELOG_VCS_SERVER_URL the full URL of your VCS server - without a trailing / (e.g. https://your.vcs.example)
    VERSION_CONTROL_CHANGELOG_VCS_PROJECT the name of the project (or user) on the VCS server
    VERSION_CONTROL_CHANGELOG_VCS_REPOSITORY the name of the repository of the project (or user)
    VERSION_CONTROL_CHANGELOG_VCS_BRANCH the branch that should be used for reading and writing the changelog (e.g. cms-changes)
    VERSION_CONTROL_CHANGELOG_VCS_FILENAME the name of the file that should be used (e.g.

    Important: Make sure that the assigned Bitbucket user has write permissions in the repository.
    There is no need to create the branch or the file in the repository, the extension takes care of this. This also means that in case you delete the file or the branch it will be automatically recreated on the next execution of the extension.

    3. Add the extension to your installation

    1. clone (or download) this repository to your local machine - alternatively you can install the package from npm and run the following next steps in the folder of the module
    2. open a terminal and change into the directory containing the package.json
    3. run npm install
    4. run npm run build
    5. create a directory named version-control-changelog inside of your <directus-root-folder>/extensions/hooks/ directory
    6. copy the generated index.js file from the dist directory
    7. paste the copied file into the newly created directory
    8. restart your Directus instance; monitor the log during startup

    If everything works you will see the following line in the log output:

    01:23:45 ✨ Version Control Changelog Extension Extension initialized, action handler registered
    01:23:45 ✨ Server started at http://localhost:8055

    4. Add your first changelog entry

    Once you save your first changes in the configured collection & field the log should show you the following line:

    17:32:16 ✨ Version Control Changelog Extension BitbucketVersionControl: new changelog pushed successful

    If you see it: congratulations, your setup works!

    Release History

    Version 0.8.1


    • fixing a bug where a hardcoded field name (not respecting the settings) causes a crash
    • improved prefix of extension in logger messages

    Version 0.8.0


    • initial release for Bitbucket

    Future possibilities

    These are things that would make sense, but it is not granted that it will be implemented

    • [ ] support "auto-create" of the required collection(s) and field(s) on first run
    • [ ] allow multiple changelogs (multiple collections writing to multiple repositories)
    • [ ] add GitHub and / or GitLab as target systems
    • [x] added to npm (to allow installation via npm once it is available)
      • [ ] confirm it works or do required adjustments once available
    • [ ] add to the Extension Marketplace once it is available


    npm i @bix-digital/directus-extension-version-control-changelog

    DownloadsWeekly Downloads






    Unpacked Size

    667 kB

    Total Files


    Last publish


    • gerardcl
    • manuelfeller
    • bix_digital_lab