Mage home pagelight logo
Version control
Git integration

​
Configure Git settings

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 authentication

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:

  1. 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.
  2. Go to your Mage settings: Mage settings
  3. Navigate to the “Git settings” section of the Mage settings page.
  4. Set up your SSH key so that your machine can access Github, if you haven’t already. Check out this sections 3 and 4 of this guide to set up your SSH key.
  5. Select SSH as the authentication type.
  6. Fill out the form:
    1. Remote repo url: Your Github repository’s remote url. Use the SSH link instead of HTTPS link. Github url
    2. 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.
  7. 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):
    1. Username: Your git username. If you push to your remote repo, this username will show up next to your commits.
    2. Email: Your git email. Used for the same purpose as your username.
    3. 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.
  8. Fill out the optional sync fields if you are using a Git sync (this is a separate Git feature):
    1. 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.
    2. Sync before each trigger run: If this field is checked, then Mage will sync with Github before each trigger is run.
  9. Save your Git settings

​
HTTPS/Token authentication

  1. Ensure that .preferences.yaml file is added to your repo’s .gitignore file so that your Git settings aren’t pushed to Github, unless you want them to.
  2. Go to your Mage settings: Mage settings
  3. Navigate to the “Git settings” section of the Mage settings page.
  4. Create a Git access token and save it for later.
    1. GitHub
    2. GitLab
  5. Fill out the form:
    1. Remote repo url: Your Github repository’s remote url. Use the SSH link instead of HTTPS link. Github url
    2. 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.
  6. Fill out the remaining git fields:
    1. Username: Your git username. Your username will be used for token authentication.
    2. Email: Your git email.
    3. Access token: Enter the Git access token that you created in step 4.
  7. Fill out the optional sync fields if you are using a Git sync (this is a separate Git feature):
    1. 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.
    2. Sync before each trigger run: If this field is checked, then Mage will sync with Github before each trigger is run.
  8. Save your Git settings

​
Git sync

Git sync is a separate feature from enabling Git within Mage. If you want to be able to perform Git actions such as pushing, pulling, creating new branches, etc., you don’t want to enable this feature.

This feature should only be used if you are not planning to make any local changes to your Mage repository.

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.

​
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.

Git settings

  • GIT_REPO_LINK: corresponds to Remote repo url
  • GIT_REPO_PATH: corresponds to Local directory path
  • GIT_USERNAME: corresponds to Username
  • GIT_EMAIL: corresponds to Email
  • GIT_AUTH_TYPE: Authentication type, options: “ssh” or “https”

Git sync settings (optional)

  • GIT_BRANCH: corresponds to Branch name
  • GIT_SYNC_ON_PIPELINE_RUN: corresponds to Sync before each triggger run, options: 0 or 1

Authentication environment variables (optional). Mage will use your saved git secrets if they are available.

  • GIT_SSH_PUBLIC_KEY: SSH public key encoded in base64, used for ssh auth type
  • GIT_SSH_PRIVATE_KEY: SSH private key encoded in base64, used for ssh auth type
  • GIT_ACCESS_TOKEN: Git access token, used for https auth type