free as in freedom free software to keep track of your deployment journal
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Generic Deployment To Do System

Free as in freedom and generic approach to cover handling of deployment to does in a generic way.


  • keep track of your deployment todo while switching branches


  • create file for each deployment todo into a global directory covered by the vcs
  • just execute the deployment todo fitting to your environment
  • record executed deployment todo into a local directory
  • compare current local state with current global state
    • execute missing
    • revert not fitting


  • each deployment todo has a uuid
  • each deployment todo can cover one to many environments
  • each deployment todo can be executed manually or automatically
  • no fixed file format for a deployment to do
  • decoupled from your used vcs since the vcs keeps track of the current state of all available deployment to dos

Shipped with format

//file with a name like "2a7f46c9-32ac-42b6-96e2-8fe2df51bdd8.json"
// in the global path like "<project root>/data/deployment_journal/global"
    "uuid": "<string>",
    "created_at": "<yyyy-mm-dd hh:ii:ss>",
    "created_by": "<name or unique identifier>",
    "list_of_affected_environments": [
            "name": "development"
            "name": "production"
            "name": "staging"
            "name": "testing"
    "name": "my example journal entry",
    "task_to_commit": {
        "class_name_of_handler": AApplication\\Feature\\DomainModel\\V1\\Service     "content": "#!/bin/bash",
        "description": "this is a demo entry"
    "task_to_revert": {
        "class_name_of_handler": Application\\Feature\\DomainMApplication\\Feature\\DomainModel\\V1\\Service",
        "description": "this is a demo entry"
    "version": "<integer>"


to do

  • create domains
    • commit handler
      • execute as shell script
      • output on the command line
    • revert handler
      • execute as shell script
      • output on the command line
  • implement code for domain storage comparator (compares content of two given storage)
  • implement code for domain unified journal (what is a task, fetch list of task, fetch single task, add single task, delete single task - just the interfaces)
  • implement code for domain shipped with journal (local file path storage)
  • implement code for domain journal comparator (compares to different paths)
  • implement code for domain commit handler (what has to be executed to commit a task - execute task if possible, on success copy it to the local storage)
  • implement code for domain revert handler (what has to be executed to revert a task - execute undo if possible, on success remove it from the local storage)
  • create lovely cli
  • put each domain code into a dedicated repository
  • put generic/feature related code to dedicated repository (or multiple)
  • ask to rename this as täptn's log

on it

  • implement message pack formatter
  • create domains
    • shipped with implementation
      • entity (json)
      • storage (file system)
  • create zf console commands
    • environment list
    • task-handler list
  • convert bin/commands to zf console commands
    • entity-create
    • system-adjust
    • system-audit
  • convert filesystem storage to use flysystem


  • added name to the entity
  • created command line calls
    • entity create
    • entity list [--all] [--local] [--global]
    • system adjust
    • system audit
  • create domains
    • unified storage comparator (fetch a list of files that differs from global to local path)
    • journal comparator (check if that journal needs to be done in the current environment)
    • unified journal interface
      • entity (get uuid, environment)
      • storage
  • converted bin/commands to zf console commands
    • entity-list
  • setup zf cli application

won't do



  • use post-checkout and post-merge
  • investigate current system status
    • read deployment to do list
    • read current branch name
    • read latest vcs commit id
    • read fitting (branch dependend) log
  • compare deployment to does with steps in the local log
  • output or handle deployment to do list entry
  • commit each finished entry into the log
  • save current git branch and latest commit
  • remove local (branch dependend) log if branch is deleted via git (post branch delete hook?)

Scribbled Codes

Configurable Settings

Either you add the relative path to the configuration file to each command or you put it into the path "<project root>/configuration/deployment_journal/configuration.php".

return [
    //uuid dns or url to replace uuid4 with uuid5
    'current_environment'           => <string>,
    'current_user_name'             => <string>,
    'execute_tasks_automatically'   => <boolean>,
    'list_of_environment'           => [
    'path_to_the_global_journal'    => <string>,
    'path_to_the_local_journal'     => <string>

Unordered Ideas

  • entries can be stored in any kind of format
    • a generic interface is used to check if this entry needs to be committed or not
    • a generic interface is used to check if this entry needs to be reverted or not
  • entries are stored as json files
  • entries are stored in the directory path "<yyyy>/<mm>/<dd>/<uuid>.json"
  • each done entry is copied to the local journal (the create date is the execution date)
  • auditing the system means comparing the global and the local journal
  • switching the environment is not supported yet
  • switching the data mapper is not supported yet
  • entry can be done/committed or undone/reverted
  • undo or revert a entry is a rollback?

Next Milestone

  • add archiving (zipping directories older than x days)
  • add support for local.configuration.php an system.configuration.php to ease up maintaining 'current_environment' and 'current_user_name' from the rest.
  • environment depended variables
  • add --full to audit-system (to enable the list of entries in status "committed")

To Do

  • Filter by current environment in storage

Nice To Have Or Just As Example

  • configurable formatter/InputHandler/OutputHandler to start using this side beside your current project until you have migrated your infrastructure

Things To Do

  • find fitting cli environment to run with
  • list of command
    • create-entry | entry-add|create - generates new entry
      • bin/entry-create
    • list-entries | entry-list - show all available entries with uuid, description and status (done, todo, to undo) - the log
    • audit-system | system-audit|check|review - validates if entries needs to be done or undone
    • update-system | system-fix|update|adjust|level|modulate|redeem|equalize - executes entries that needs to be done or undone