Introduction
- JS7 JOC Cockpit can be configured to interface with Git repositories to store and to rollout its configuration objects such as workflows and jobs.
- Configuration objects can be versioned (tagged) with Git and can be rolled out to different JS7 environments via Git. This allows to create and to test workflows in a development environment and to perform rollouts to a production environment by use of a Git repository.
- A connection to a Git repository is considered an additional option to manage versions and rollouts of JS7 configuration objects.
- The Git Repository Interface is made available in two steps:
Object Mappings
Configuration Objects
Environment-independent Objects
JS7 configuration objects that can be rolled out across environments include
- Workflows
- Locks
- File Order Sources
- Notice Boards
Such objects can be managed with JS7 in a way that allows to re-use the objects - without any changes - across rollout environments such as dev, test, prod.
Environment-related Objects
The following configuration objects typically hold values that are specific for an individual rollout environment and therefore usually are added to a separate repository. Such objects should not be rolled out across environments.
- Job Resources
- Calendars
- Schedules
Configuration Mappings
The JS7 inventory is organized by folders.
- Folders hold configuration objects such as workflows etc. and any level of sub-folders.
- Folders are the basic unit for JS7 - Permissions, for example, users can be granted access to specific folders only.
- Folders allow to perform bulk operations such as to deploy, to release, to remove and to rename configuration objects.
Folders can be mapped to Git repositories managed by the same or by different Git servers like this:
The mapping of folder objects to repositories implies
- user access:
- users with JS7 access permissions to manage folders and to access the Git repository can manage configuration objects in JOC Cockpit and can commit, push, pull configuration objects to/from Git,
- users with JS7 access permissions to manage folders but without access to the Git repository can manage configuration objects in JOC Cockpit,
- users with JS7 access permissions to view folders do not require Git access.
- folder usage:
- if a single Git repository should be used then all folders have to be available from a single root folder,
- for use with a number of Git repositories each folder maps to a different repository,
- folders can remain without Git integration for local management and deployment.
JOC Cockpit maps folders to Git repositories and stores the respective Git repository URL for each folder in its inventory.
Git Access
User Access
Each user holds an individual set of credentials to connect to a Git server.
The following settings are stored with a user's profile:
git_account
- account that is used to connect to a Git server
git_key
- the user's private key for Git access
git_access_token
- the access token for Git access that works as an alternative to use of a private key
If repositories are used from a number of Git servers that require different sets of user credentials then separate user accounts in JOC Cockpit have to be used.
Repository Access
- The JS7 - REST Web Service API executes a set of Git operations by use of the Git Command Line Client.
- Any operations to add configuration objects to a repository, to stage, commit, push, pull and to merge objects are available from the JS7 REST Web Service API.
- The JOC Cockpit offers the user interface for respective Git operations.
- Users are free to use additional tools such as Git Extensions to manage repositories.
Git Operations
Management
JS7 configuration objects are transparently managed in a Git repository via the JS7 REST Web Service API. In addition, tools such as Git Extensions and Git command line clients can be used for repository operations.
JOC Cockpit holds a number of local repositories inside the JETTY_BASE/resources/joc/repositories
folder. Each root-level folder in the JS7 Configuration view can be mapped to a Git repository.
- The local repository for a JS7 root-level folder is created when a user performs the
checkout
/clone
operation for the Git repository via JOC Cockpit. - The local repository is persistent and is updated from the JOC Cockpit database (
store
operation) and from the remote Git repository (pull
operation). - The remote Git repository is updated from the local repository by use of the
push
operation. - The JS7 - Cleanup Service removes any local repositories if the JS7 root-level folder no longer exists, i.e. if a root-level folder is dropped from JOC Cockpit.
The following operations are available:
git-checkout
- checks out a specific branch or tag from the Git repository to the local repository
git-clone
- initially clones a Git repository to a local repository
git-add
- adds or updates (stage) a new or modified configuration object on the filesystem to the local repository
git-reset
- unstages a modification from the local repository, the modified file in the filesystem remains unchanged and still contains the modification
git-delete
- removes an already added configuration object from the local repository
git-commit
- commits newly staged configuration objects to a local repository
git-push
- pushes changes from the local repository to the remote Git repository
Versioning
Versioning of JS7 configuration objects is performed by use of the tagging capabilities of Git.
The JS7 REST Web Service API manages the Git tagging process.
The following operations are available:
git-tag
- tags a commit with a version label
git-push
- see above
Rollout
Rollout between different JS7 instances is performed by use of the Git functionality.
The JS7 REST Web Service API manages the processes for checkout and cloning.
The following operations are available:
git-checkout
- checks out a specific branch or tag from the Git repository to the local repository
git-clone
- initially clones a Git repository to a local repository
git-pull
- pulls recent changes from the Git repository to the local repository
Transfer of Configuration Objects between JOC and the Repositories
The transfer of configuration objects between the JOC Cockpit database and the repositories are manged by the JS7 JOC REST Web Service API.
The following operations are available:
- ./inventory/repository/read
- reads file tree of the local repositories filesystem folder
- ./inventory/repository/store
- stores a set of configuration objects from the JOC Cockpit database to the filesystem folder of the local repository
- ./inventory/repository/delete
- deletes a set of configuration objects from the filesystem folder of the local repository
- ./inventory/repository/update
- adds or updates a set of configuration objects in the JOC Cockpit database with the configuration objects from the locale repositories filesystem
Use Cases
Single Client - Multiple Repositories (dev, test, prod)
Scenario
- Architecture
- A dedicated JOC Cockpit instance is used with Controller and Agents for each rollout environment such as dev, test, prod.
- A Git repository is used per folder and per rollout environment (dev, test, prod), each JOC Cockpit instance is acting on a specific repository per rollout environment.
- The Git repository is used to hold a copy of JS7 configuration objects, to create versions of JS7 configuration objects and to merge branches such as dev => test, test => prod.
- Users
- All users act in the same JOC Cockpit instance of the respective rollout environment that is a single client to the Git server.
- Changes to the Git repositories are performed by the users' individual accounts and are added to each repository and branch such as dev, test, prod.
- Rollout
- Deployments are performed from a single source (JOC Cockpit) to each Controller and Agents per rollout environment (dev, test, prod).
- The Git repositories are used to checkout and to clone branches and to rollout JS7 configuration objects to different Controllers and Agents, such as dev => test => prod.
- The Git repository can be used to fallback (pull) to previous versions of configuration objects, however, only one version is available with a given JOC Cockpit instance at a given point in time.
Branches marked as "env" are specific for an environment and are excluded from rollout. Branches marked as "rollout" are environment-independent and are forwarded across scheduling environments.
Repository Operations
- management
- versioning
- rollout
- force overwrite
Requirements
- The JOC Cockpit database holds the configuration objects:
- each JOC Cockpit instance is connected to its own database,
- each Git branch is mapped to an individual JOC Cockpit instance,
- the database can be updated from a Git branch.
- each Git branch makes use of its own version of configuration objects.
Multiple Clients - Multiple Branches (dev, test, prod)
Scenario
- Architecture
- A dedicated JOC Cockpit instance is used with each Controller and Agents for each user in the dev rollout environment.
- A dedicated JOC Cockpit instance is used with each Controller and Agents for all users in the test and prod rollout environments.
- Individual Git repositories are used per folder and per rollout environment by JOC Cockpit instances, each instance is acting on a specific repository and branch per rollout environment.
- The Git repository is used to hold a copy of JS7 configuration objects, to create versions of JS7 configuration objects and to merge branches such as dev => test, test => prod.
- Users
- Users act in individual JOC Cockpit instances of the dev rollout environment as multiple clients to the Git server.
- Users act in the same JOC Cockpit instance of the test and prod rollout environment as a single client to the Git server.
- Changes to the Git repositories are performed by the users' individual accounts to a each branch.
- Rollout
- Deployments are performed from a multiple sources (JOC Cockpit) to the connected Controller and Agents per rollout environment (dev, test, prod).
- The Git repositories are used to checkout and to clone branches and to rollout JS7 configuration objects to different Controllers and Agents, such as dev => test => prod.
- The Git repository can be used to fallback (pull) to previous versions of configuration objects, however, only one version is available with a given JOC Cockpit instance at a given point in time.
Branches marked as "env" are specific for an environment and are excluded from rollout. Branches marked as "rollout" are environment-independent and are forwarded across scheduling environments.
Repository Operations
- management
- versioning
- rollout
- force overwrite
Requirements
- The JOC Cockpit database holds the configuration objects:
- each JOC Cockpit instance is connected to its own database.
- each Git branch is connected to one or more JOC Cockpit instances.
- Each branch makes use of an individual version.
- Each user (client) makes use of an individual JS7 instance using JOC Cockpit and database, Controller and Agents