Git integration

Configure Git in Mage

By using the Git integration through Mage, Mage will automatically set your local repo as a safe directory (i.e. git config --global --add safe.directory <local repo path>)

SSH keys with passphrase are not supported

The Git integration currently does not support repositories that require an SSH key with a passphrase.

You can, however, use the Mage terminal and the git CLI to perform your git actions. You’ll still need to generate your SSH keys as normal. You can start a ssh-agent in the terminal so that you don’t have to enter your SSH key passphrase every time you perform an action.

eval $(ssh-agent -s) && ssh-add ~/.ssh/id_rsa

To use the Mage Git integration, you will need to first configure Git settings. The following instructions are tailored to Github, but the Git integration can work with other Git providers as well, such as Gitlab:

Check preferences.yaml

Ensure that .preferences.yaml is added to your repo’s .gitignore file so that your Git settings aren’t pushed to Github, unless you want them to.

Navigate to your Mage settings

Wizard > Settings

Navigate to the 'Git settings' section

Set up your SSH key

This will allow your machine to access GitHub. Check out this sections this guide to set up your SSH key.

Select SSH as the authentication type.

Fill out the form

Remote repo url: Your Github repository’s remote url. Use the SSH link instead of HTTPS link.
Local directory path: The directory in your machine that will be synced with the Github repository. If this field is omitted, it will default to the path determined by Python’s os.getcwd(). You can check what your current working directory is in a Scratchpad block.

Fill out the remaining optional, but recommended fields.

Filling out these fields will allow Mage to recreate your git and SSH settings if they are deleted (i.e. if your container restarts):

Username: Your git username. If you push to your remote repo, this username will show up next to your commits.
Email: Your git email. Used for the same purpose as your username.
SSH public key in base64, SSH public key in base64: Enter your SSH public and private key encoded in base64. You can follow the instructions in the field description if you want to Mage to save your SSH keys.

Fill out the optional sync fields if you are using Git Sync

Git sync is a separate Git feature.

Branch name: This field is only used when running a Git sync. Git syncs can be run either from this Git settings page, or before every trigger run.
Sync before each trigger run: If this field is checked, then Mage will sync with Github before each trigger is run.

Save your Git settings

(Optional) One-way sync

Git sync is a separate Git feature that allows you to tie your local project to a remote repo. Git sync is particularly useful for deployment— for example if you’d like a hosted Mage instance to stay up-to-date with a repo.

Enabling Git sync limits Git to a unidirectional sync. This means that changes made to your local repo will be overwritten by the remote repo. To sync both ways, leave Git sync disabled.

Running a Git sync will overwrite all local changes and replace them with the code in the specified remote branch. Git syncs can be run either from the Git settings page, or before every trigger run if you selected the Sync before each trigger run field.

To enable Git Sync, navigate to the settings page after you’ve configured your Git settings and tick the Git Sync box.

Git settings as environment variables

You can choose to pass in Git settings as environment variables. Mage will read from these environment variables to configure your Git repo.

Setting	Variable	Description	Required
Git settings	`GIT_REPO_LINK`	corresponds to `Remote repo url`	✅
Git settings	`GIT_REPO_PATH`	corresponds to `Local directory path`	✅
Git settings	`GIT_USERNAME`	corresponds to `Username`	✅
Git settings	`GIT_EMAIL`	corresponds to `Email`	✅
Git settings	`GIT_AUTH_TYPE`	Authentication type, options	✅
Git sync settings	`GIT_BRANCH`	corresponds to `Branch name`	🚫
Git sync settings	`GIT_SYNC_ON_PIPELINE_RUN`	corresponds to `Sync before each trigger run`, options	🚫
Git sync settings	`GIT_SYNC_ON_START`	corresponds to `Sync on server start up`, options	🚫
Git sync settings	`GIT_SYNC_ON_EXECUTOR_START`	If set to “1”, Mage will attempt to run a git sync every time an executor is started, options	🚫
Authentication environment variables	`GIT_SSH_PUBLIC_KEY`	SSH public key encoded in base64, used for ssh auth type	🚫
Authentication environment variables	`GIT_SSH_PRIVATE_KEY`	SSH private key encoded in base64, used for ssh auth type	🚫
Authentication environment variables	`GIT_ACCESS_TOKEN`	Git access token, used for https auth type	🚫

Get Started

Concepts

Git integration

Configure Git in Mage

(Optional) One-way sync

Git settings as environment variables

Get Started

Concepts

​Configure Git in Mage

​(Optional) One-way sync

​Git settings as environment variables

Configure Git in Mage

(Optional) One-way sync

Git settings as environment variables