In the webapp directory, update local.properties with a git directory path e.g., 'git.default.path=C://app//tomcat9//webapps//phixflow//git', and ensure the new empty directory is created. Restart tomcat and start the PhixFlow instance for the git repository to be configured.

If multiple users try to take and restore snapshots at the same time, an error message will display to try again later.

System Configuration

In order to store applications in a Git Repository, the a Git Repos Location must be set. A default value is populated for all new and upgraded systems. If your system has no value, follow the below steps to set this.

1. In PhixFlow, from the

   Insert excerpt
   _administration _administration nopanel true

    menu, open System → 

   Insert excerpt
   _system_config _system_config nopanel true

2. In the System Directories section, enter a value for Git Repos Location,e.g. ${export_loc}/../git/

3. Insert excerpt
   _save _save nopanel true

    your changes

Git Repositories 

1. A new Git Repository Head object will be defined

   1. This will be visible in the full repository and is not owned by an application

   2. System administrators and people with appropriate Git permissions will be able to create/view/edit/delete them

   3. The following properties will be available

      1. Name (must be unique)

      2. Description

      3. Type - local or remote

      4. For remote repositories:

         1. Url

         2. Branch

         3. username

         4. Authentication type - password / key

         5. password

         6. key

      5. Status - read only

      6. Status message - read only

Structure

1. The Git repository layout will be structured so that it facilitates manual code review and in as far as is sensible reflects the Phixflow Repository view

2. The name of each export file will be <container_type>/<container_name>/<object_type>/<safe_name>-<UID>.xml

   1. container_type: Application or Package

   2. container_name: Name of the container - is guaranteed to be unique in the system

   3. object_type: Type of the object, as displayed on property editors/repository (not the class name)

   4. safe name: Object name, sanitized so that it is filename safe

   5. UID: object UID to ensure all filenames are unique.

3. Handling of special characters such as '/' in container names should be tightened up to ensure generated names are safe

4. The contents of the files will be compatible with the ImportFileService

5. If an object has been deleted then it should be deleted from the repository

6. If an object has been renamed then the original file should be deleted and the new file created

   1. Typically Git's rename detection will identify this as a rename

Creating a New Git Repository

1. When a new local repo is first saved

   1. The directory ${gitrepo_loc}/${name} will be created

   2. It will be initialized as a new empty git repo with a single branch with a default name (configurable via properties, ‘main’)

   3. The branch will be checked out.

   4. The data will be persisted in the database  

   5. The status will be set to Synced

   6. Failure to create the directory/perform the local git operations should result in an error without the object being persisted.

2. If a repo is renamed then

   1. The local directory will be renamed on disk

   2. The data will be persisted in the database

   3. Failure to rename the directory/perform the local git operations should result in an error without the object being persisted.

3. It is not permitted to change the type of a local repository

4. When a remote repo is first saved

   1. The directory ${gitrepo_loc}/${name} will be created

   2. It will be initialized as a new remote tracking repository 

      git init
   3. git remote add origin {remote-url}

   4. The data will be persisted to the database

   5. The status will be set to Pending

   6. Failure to create the directory/perform the local git operations should result in an error without the object being persisted.

5. If any of the remote specific settings are change the status will be set to Pending

6. If a repository is deleted the contents on disk should also be deleted

   1. A suitable warning message should be displayed before deleting a repository

      1. For local repositories this should stress it will permanently delete the files.

      2. For remote repositories it should be clear this will delete local files but will not modify the remote repository.

7. A test button will be available next to the settings of remote repository

   1. This will trigger a synchronous operation to attempt to connect to the remote url with the given credentials

   2. A result message should be returned indicating the error or success.

8. A sync operation will be available next to the status, this operation will also be triggered before an export or import.

   1. On local repositories this will revert any local changes to the git repo

      git checkout -f -B <branch>

   2. On a remote repository this will

      1. Connect to the remote repository and fetch

      2. Reset the specified branch replacing any local changes

         git fetch origin git checkout -f -B <branch>

   3. Status should be updated to synced with an appropriate message if it succeeds

   4. On failure an error should be shown indicating the cause and the status and message updated.

Configuration Export

1. For users with appropriate permissions the configuration export screen will give the option whether to export to file or to Git.

2. Exporting to Git will allow selection of a configured Git Repo

3. The system will ensure only a lock is taken so only a single process can be exporting/importing from the Git repository at a time.

4. Before export starts a sync will be performed and any errors reported.

5. The exported directory structure must be in a form that is understandable to users manually looking at the Git change log or history.

6. The author of the commit will be generated in the form “FirstName LastName <email>” of the active user

7. The description will be used as the base commit message

8. The export process will write (and deleted) files with the appropriate names and contents to the local git repository

9. For remote repositories a push will be performed to update the remote repository with the changed files.

10. Full and partial exports will be supported as with current file behaviour

11. The export task log will include the Git target url, branch and commit hashes of the export.

Configuration Import

1. For users with appropriate permissions the import export screen will give the option whether to import a file or from Git.

2. Importing from Git will allow selection of a configured Git Repo

3. The system will ensure only a lock is taken so only a single process can be exporting/importing from the Git repository at a time.

4. Import from Git will always use the full contents of the remote branch for the import

   1. Protect on import settings will be honoured.

5. A sync operation will be used before the import

6. The contents of the local git repo will be loaded and used for the import operation.

   1. It is an error if the branch does not exist or if the branch does not contain a valid export

7. The import task log will include the Git target url, branch and commit hashes of the import.

Security

1. In phase 1 Git repositories should only be usable by administrators, users must also have the relevant import/export permissions

2. In later phases separate permissions should exist to create new Git Repositories, and User group base security determining who can update/delete the configuration, import from (read) or export to (write) each Git repository. In addition standard import/export permissions are required.

   1. By default repositories should be private, owned by the creator.

3. Repository passwords and private keys should be handled as local secrets