Skip to content

Git ​

SPACE provides integrated Git version control for Python scripts, notebooks, and other project files. You can clone repositories, track changes, commit updates, and synchronize with remote repositories directly from SPACE Python.

Git is separate from the Planning Analytics Git integration, which manages IBM Planning Analytics model assets.

SPACE works with Git repositories accessible over SSH, including repositories hosted on GitHub, GitLab, Bitbucket, Azure DevOps, and self-hosted Git servers.

Working with Git ​

Open SPACE Python. The File Browser displays the shared Python workspace, and the Git icon in the left sidebar opens the Git interface.

Clone or initialize a repository ​

Git sidebar with options to initialize or clone a repository

To clone an existing repository:

  1. Open the File Browser and navigate to the location where you want to keep the repository, usually the workspace root.

  2. Open the Git tab in the left sidebar and select Clone a Repository.

  3. Enter the repository's SSH URL, for example:

    text
    git@github.com:organization/repository.git
  4. Complete the clone operation, then open the cloned repository folder in the File Browser.

A single shared repository is a good starting point. /git is a suggested repository location, but you can choose another folder.

To start a new repository: Create and open a dedicated project folder, select the Git tab, and choose Initialize a Repository. Avoid initializing a repository at the workspace root unless you intentionally want to version the entire workspace.

Review, commit, pull, and push ​

When you open a folder within a Git repository, the Git sidebar shows its changes, commit history, and branches.

Git sidebar showing changed files, commit controls, history, and branches

  • Review changes: Check the Changed and Untracked sections for modified or newly created files.
  • Commit: Stage the files you want to include, enter a commit message, and select Commit.
  • Pull: Use the pull action in the Git toolbar to retrieve and integrate remote changes.
  • Push: Use the push action to publish your local commits to the remote repository.
  • Branches and history: Use Branches and Tags and History to work with branches and review previous commits.

A commit is saved locally; it is not uploaded to the remote repository until you push it.

You can add a .gitignore file to a repository to exclude temporary files, notebook checkpoints (such as .ipynb_checkpoints/), and other files that should not be tracked by Git.

The Python workspace is shared, so users working in the same repository should coordinate changes to avoid conflicts.

Using Git across environments ​

If you use multiple Planning Analytics environments, you can use the same Python Git repository across them. Each environment can run code from its own branch or a specific commit.

SetupWhen to use itTrade-off
One SPACE instance with a folder per environmentClone the same repository into separate folders, such as DEV and PROD. Add a QA folder if you have a QA environment. The clones can use the same SPACE SSH key.The Python workspace is shared, so users with write access can edit production files.
Separate SPACE instance for productionKeep production files, jobs, and credentials on a dedicated SPACE instance. Your other environments can share an instance.You manage an additional SPACE deployment.
One SPACE instance per environmentGive each environment its own workspace, access controls, and configuration.This requires the most infrastructure and administration.

A SPACE job runs the script at its configured path. When you approve a new version in Git, update the checkout for the target environment before running the job.

Git authentication ​

Git access is configured once per SPACE installation, rather than separately for each SPACE user. Users share the remote repository permissions granted to the configured SSH key.

  • Succeedium-managed installations: Succeedium configures Git and provides the SSH public key. Your Git administrator registers the key with the repository or Git provider.
  • Client-managed installations: A server administrator configures SSH access using the instructions below.

A read-only key allows users to clone, fetch, and pull, and they can still make local commits. Write access is required to push commits to the remote repository, subject to any branch protection or other Git provider restrictions.

Client-managed configuration ​

Standard SPACE installations include two configuration templates in config/python/git/:

text
.gitconfig.example
ssh_config.example

The Git configuration directory is already mounted in the SPACE Python service. No Docker Compose changes are required for a standard installation.

1. Prepare the configuration files ​

From your SPACE installation directory, create the active configuration files from the templates:

bash
sudo cp ./config/python/git/.gitconfig.example ./config/python/git/.gitconfig
sudo cp ./config/python/git/ssh_config.example ./config/python/git/ssh_config

Edit .gitconfig to specify the default commit identity, for example:

ini
[user]
    name = SPACE
    email = space@example.com

Use a name and email appropriate for your organization. This is the default identity for commits made through SPACE.

Edit ssh_config for your Git provider. For GitHub, use:

ssh-config
Host github.com
    HostName github.com
    User git
    IdentityFile /space-git/space_git_key
    IdentitiesOnly yes
    UserKnownHostsFile /space-git/known_hosts
    StrictHostKeyChecking yes

For another provider, update the host settings and use the SSH repository URL supplied by that provider.

2. Generate and register an SSH key ​

Generate a dedicated Ed25519 key pair on the SPACE server:

bash
sudo ssh-keygen -t ed25519 -f ./config/python/git/space_git_key -C "SPACE Git" -N ""

This creates space_git_key (private key) and space_git_key.pub (public key). The empty passphrase supports unattended Git operations; keep the private key protected as described below.

Display the public key:

bash
sudo cat ./config/python/git/space_git_key.pub

Register the public key with your Git provider. For GitHub, open the repository's Settings → Deploy keys → Add deploy key, paste the public key, and enable Allow write access if SPACE users need to push changes. For other providers, follow their corresponding SSH key setup procedure.

Grant only the permissions required for the repository.

3. Configure trusted SSH hosts ​

Retrieve the Git provider's SSH host key and check its fingerprint against the fingerprint published in the provider's official documentation before trusting it.

For GitHub:

bash
tmp_file=$(mktemp)
ssh-keyscan -t ed25519 github.com > "$tmp_file"
ssh-keygen -lf "$tmp_file"

Compare the displayed fingerprint with GitHub's published SSH key fingerprints.

If the fingerprints do not match, do not save or trust the host key. Investigate the mismatch before continuing.

Once verified, save the key:

bash
sudo install -m 600 "$tmp_file" ./config/python/git/known_hosts
rm -f "$tmp_file"

For other providers, use their hostname and officially verified host key.

After setup, the configuration directory should contain:

text
config/python/git/
├── .gitconfig.example
├── ssh_config.example
├── .gitconfig
├── ssh_config
├── space_git_key
├── space_git_key.pub
└── known_hosts

4. Secure the configuration ​

Apply restricted ownership and permissions to the directory and all files:

bash
sudo chown -R root:root ./config/python/git
sudo find ./config/python/git -type d -exec chmod 700 {} +
sudo find ./config/python/git -type f -exec chmod 600 {} +

Repeat these commands after adding or replacing configuration files. Never store the private SSH key in the shared Python workspace or commit it to a repository.

5. Apply and verify ​

Restart the SPACE Python service to load the Git configuration. For the standard Docker Compose installation:

bash
docker compose \
  --env-file ./config/.env \
  --env-file ./config/secrets.env \
  up -d --no-deps --force-recreate space-python

Open SPACE Python, clone the repository using its SSH URL, make a test commit, and push it if the key has write access. If authentication fails, check the public-key registration, SSH host configuration, and repository permissions.