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:
- 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. - Go to your Mage settings:
- Navigate to the “Git settings” section of the Mage settings page.
- 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.
- 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’sos.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 a Git sync
(this 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
HTTPS/Token authentication
- 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. - Go to your Mage settings:
- Navigate to the “Git settings” section of the Mage settings page.
- Create a Git access token and save it for later.
- 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’sos.getcwd()
. You can check what your current working directory is in a Scratchpad block.
- Fill out the remaining git fields:
Username
: Your git username. Your username will be used for token authentication.Email
: Your git email.Access token
: Enter the Git access token that you created in step 4.
- Fill out the optional sync fields if you are using a Git sync
(this 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
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