API v1 - Git Integration
Overview
This article is a guide to using the source control management (SCM) API in Matillion ETL. Matillion ETL uses Git for its version control, allowing teams to track a project's changes (both small and large) with speed and efficiency.
Important Information
- Consider whether Git integration is appropriate for your Matillion ETL practices with our When to Choose Git article.
- Git integration
- Git FAQ
- If you are new to Matillion ETL's API, read our Matillion API introduction.
- Explore the v1 API map.
- To jump to the v1 API, just run {host:port}/rest/v1 in your browser.
- Git integration in Matillion ETL is an Enterprise Mode feature. Read about the benefits of upgrading your licence to Enterprise Mode here.
- All information in <angle brackets> should be replaced with information based on your own configuration.
Initialise A Local Repository
To initialise a local repo using the Matillion v1 API, make the following POST call:
<instanceaddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>/scm/init
Here is an example of this request with variables added (the instance address has not been added):
{host:port}/rest/v1/group/name/Docs_Project/project/name/Docs/version/name/default/scm/init
The variables in the above example are listed immediately below for added clarity. For security reasons, the instance address remains hidden.
- groupName = Docs_Project
- projectName = Docs
- versionName = default
Here is the endpoint as seen when running the {host:port}/rest/v1 in a browser:

Init local repo endpoint
The table below documents the type of API endpoint, the body (in a JSON format), a description of the endpoint, and any pertinent notes that users should consider.
Method | Body (JSON) | Description |
---|---|---|
POST |
{ "commitMessage": "<Your Commit Message>", "userIdentifier": { "username": "<username>", "emailAddress": "<emailaddress>" } } |
Initialises a new repository in this Matillion ETL version. This request creates an initial Git commit within Matillion ETL.
|
Clone Remote Repository
To clone a remote repository, make the following POST call:
<instanceaddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>/scm/clone
Here is an example of this request with variables added (the instance address has not been added):
{host:port}/rest/v1/group/name/Docs_Proj/project/name/Docs/version/name/default/scm/clone
Here is the endpoint as seen when running the {host:port}/rest/v1 in a browser:

Clone remote repo endpoint
The table below documents the type of API endpoint, the body (in a JSON format), a description of the endpoint, and any pertinent notes that users should consider.
Method | Body (JSON) | Description |
---|---|---|
POST |
{ "remoteURI":"<URL>", "auth": { "authType": "HTTPS", "username": "<username>", "password": "<password>" } } |
Clone an existing remote repository in this Matillion ETL version. Successful requests will initialise from or clone your remote repository.
|
Switch Commit
To switch to another Git commit using the API, make the following POST call:
<instanceaddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>/scm/switchCommit
Here is an example of this request with variables added (the instance address has not been added):
{host:port}/rest/v1/group/name/Docs_Proj/project/name/Docs/version/name/default/scm/switchCommit
Here is the endpoint as seen when running the {host:port}/rest/v1 in a browser:

Switch commit endpoint
The table below documents the type of API endpoint, the body (in a JSON format), and a description of the endpoint.
Method | Body (JSON) | Description |
---|---|---|
POST |
{ "commitID": "<ID>" } |
Switch to an existing commit by passing the commit ID. You can find commit IDs by using the 'getState' endpoint detailed in the 'Get Commits' section of this article.
|
Fetch from Remote Repository
To perform a fetch from a remote repository, make the following POST call:
<instanceaddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/scm/fetch
Here is an example of this request with variables added (the instance address has not been added):
{host:port}/rest/v1/group/name/Docs_Proj/project/name/Docs/scm/fetch
Here is the endpoint as seen when running the {host:port}/rest/v1 in a browser:

Fetch from remote repo endpoint
The table below documents the type of API endpoint, the body (in a JSON format), a description of the endpoint, and any pertinent notes that users should consider.
Method | Body (JSON) | Description |
---|---|---|
POST |
{ "auth": { "authType": "HTTPS", "username": "<username>", "password": "<password>" }, "fetchOptions": { "removeDeletedRefs": "<true/false>", "thinFetch": "<true/false>" } } |
Fetch from a remote repository. A remote repository must be configured before fetch requests can be made.
|
Push to a Remote Repository
To push to a remote repository, make the following POST call:
<instanceaddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/scm/push
Here is an example of this request with variables added (the instance address has not been added):
{host:port}/rest/v1/group/name/Docs_Proj/project/name/Docs/scm/push
Here is the endpoint as seen when running the {host:port}/rest/v1 in a browser:

Push to remote repo endpoint
The table below documents the type of API endpoint, the body (in a JSON format), and a description of the endpoint.
Method | Body (JSON) | Description |
---|---|---|
POST |
{ "auth": { "authType": "HTTPS", "username": "<username>", "password": "<password>" }, "pushOptions": { "atomic": "<true/false>", "forcePush": "<true/false>", "thinPush": "<true/false>" } } |
Push to a remote repository.
|
Configure a Remote Repository
To configure a remote repository, make the following POST call:
<instanceaddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/scm/remote
Here is an example of this request with variables added (the instance address has not been added):
{host:port}/rest/v1/group/name/Docs_Proj/project/name/Docs/scm/remote
Here is the endpoint as seen when running the {host:port}/rest/v1 in a browser:

Configure remote repo endpoint
The table below documents the type of API endpoint, the body (in a JSON format), and a description of the endpoint.
Method | Body (JSON) | Description |
---|---|---|
POST |
{ "url": "<URL>" } |
Configure a remote repository.
|
Get Remote (returns URL)
To return the URL of your remote repository, make the following GET call:
<instanceaddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/scm/remote
Here is an example of this request with variables added (the instance address has not been added):
{host:port}/rest/v1/group/name/Docs_Proj/project/name/Docs/scm/remote
Here is the endpoint as seen when running the {host:port}/rest/v1 in a browser:

Get remote endpoint
Get Commits
To retrieve a list of each Git commit on the local repository, make the following GET call:
<instance address>/rest/v1/group/name/<groupName>/project/name/<projectName>/scm/getState
Here is an example of this request with variables added (the instance address has not been added):
{host:port}/rest/v1/group/name/Docs_Proj/project/name/Docs/scm/getState
Here is the endpoint as seen when running the {host:port}/rest/v1 in a browser:

Get state endpoint
The table below documents the type of API endpoint, the body (in a JSON format), and a description of the endpoint.
Method | Body (JSON) | Description |
---|---|---|
GET | N/A | Provides a list of commits on the local repository. |
Get Differences
To get differences between the current Matillion version and the branch head, make the following GET call:
<instanceaddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>scm/differences
Here is an example of this request with variables added (the instance address has not been added):
{host:port}/rest/v1/group/name/Docs_Proj/project/name/Docs/version/name/default/scm/differences
Here is the endpoint as seen when running the {host:port}/rest/v1 in a browser:

Get differences endpoint
The table below documents the type of API endpoint, the body (in a JSON format), and a description of the endpoint.
Method | Body (JSON) | Description |
---|---|---|
GET | N/A | Returns the difference between the current version (including uncommitted changes) and the head. |
Contact Us
If any help is needed navigating the Git API in Matillion ETL, please read the Getting Support article.