Connecting to Git / GitHub
The Magic Suite file system can use a chosen Git repository and branch as a virtual read-only folder.
For credentials, when using a GitHub URL in the Connection's "Url" field, you can use either a tranditional user name and password or one of two types of Personal Access Token (PAT) supported by GitHub - what it calls a 'fine-grained PAT' or a 'classic token'.
More information about creating a PAT can be found on GitHub here.
To set up Magic Suite apps to be able to use Git / GitHub as a file system Connection:
- If your repo is private:
- Note your username
- Note your password, or Personal Access Token (PAT), if connecting to GitHub
- Decide which branch you want to use (typically, 'main')
Then in the Admin app, under Connections (or in Report Magic -> Admin -> Connections):
- Click the Create button
- Enter a name and optionally, a description. The name specified here will be the name used in the file system
- From the Type drop-down, choose a Connection type of Git / GitHub
- In the URL field, enter the Git repository URL e.g. https://github.com/company/Repository
- Is your repo private?
- Yes: enter the GitHub user name if you want to use a user name / password combo, otherwise leave blank (it will be ignored). In the Password field, enter your GitHub password, or the PAT
- No: leave the Username and Password fields empty
- In the mandatory Configuration field, paste this and change the values:
{ "FileSystemMountPoint": "/MyGitRepo", "Branch": "mybranch" }
e.g. - Change "/MyGitRepo" to any name - this is what should be used in macros, such as
[File.xxx:]
macros - Change "mybranch" to the branch of the repository, e.g. typically just "main"
- Click Save
- Go to the Files browser in Report Magic and you should notice that a GitHub icon appears, and the repository will be cloned into the correct file structure
- Go to the Connections page (in ReportMagic it's Admin -> Connections, or in the Admin app just the Connections menu) and a green checkbox should appear in the table if the details you have entered are valid
Once this process is completed, you should then be able to access files and folders (but not write to) in the repository in your ReportMagic reports as normal, e.g. by using various [File.xxx:]
macros.
In the files browser, the name of the 'drive' is the name of the Connection. However, in macros, the path you should use is the FileSystemMountPoint.
Using Personal Access Tokens (PATs) to Access Private GitHub Repositories
You can access a private repository (e.g. with a PAT) if you are the owner, or have been invited by someone else to be a collaborator.
In order to work with Magic Suite apps (i.e. show whether the Connection is valid on the Connections page, and to be able to read the repository contents), there are a few things you should do when using GitHub, as described below.
Note that it is not necessary to enter a Username in the Connection when using a PAT. However, GitHub requires that a Username (anything at all) is sent to it. In Magic Suite 3.25, you may find that your GitHub Connections using a PAT fail and show as invalid on the Connections table - this is a bug on our part, with a fix coming soon in Magic Suite 3.26. The workaround for now is to enter anything at all in the Connection's Username field, e.g. Banana.
When using a 'Fine-Grained' PAT
To create one:
- Go to GitHub and log in
- Click your profile picture in the top-right of the page, then click Settings
- On the page that appears, scroll down and choose Developer settings from the left-hand menu
- On the page that appears, choose Personal access tokens from the left-hand menu
- Select Fine-grained tokens from the drop-down, rather than Tokens (classsic)
- Click the green Generate new token button that appears
- Give the token a name and an optional description, and choose the expiration date
- Under the Repository access section, choose either All repositories, or Only select repositories
- Under the Permissions section, expand the Repository permissions area
- Scroll down to Contents, and in the Access drop-down, choose Read-only (you can choose Read and write, but in Magic Suite we only use read only access so it is currently unnecessary)
- Scroll down and press the green Generate token button
- A pop-up appears - click the green Generate token button (yes, it makes you click such a button twice!)
- On the next page, copy the token details
- Use this token in the Password field of the Connection create/edit dialog
- Save the Connection - the status icon in the Connections table will become a green check if everything has worked
- You may also click the status icon to check its validity again
- Go to the Files browser in Report Magic and check that the repository has been cloned
When Using a 'Classic' PAT
The steps are almost identical to the above, except:
- When creating the token, choose Tokens (classic) when choosing the token type
- Instead of a name and description, you are asked to complete a mandatory Note field, that describes what the token will be used for
- There is no Repository access and Permissions sections
- Instead, in the Select scopes section, select the repo check-box, in order to give the required permissions