by Roller_Bott
The safest, most efficient way to interact with your GitHub repositories from Roblox.
[ Creator Store Hyperlink ]
[ See on GitHub ]
Feedback is appreciated! Below the introduction is a comprehensive guide to using the plugin!
Hello, DevForum. I present to you… GIT SYNC! This plugin is relatively intuitive, but I have also created a guide if you need it. GitSync allows scripters, aspiring scripters, and script users to store their work on an easily accessible cloud-based GitHub repository! If there are any errors, contact me through messages or comments!
TIP - You can move the plugin windows by dragging them from the center with your mouse!
SAFE: Confirmation popups have been added, but still make sure to be careful when pushing and pulling items! Undo doesn’t work on Source changes!
Obviously, it all starts with installing GitSync. To do this, you can either scroll down to the “Links” section or use this link. Once you have the plugin installed, it should show up in the plugins tab of Roblox Studio. If you don’t see it, try searching it up in the “Plugins” section of toolbox or restarting Roblox Studio.
Once you have GitSync installed and accessible, you will see two buttons: a toggle button (Figure 1) and a settings button. Right now, we will focus on the toggle button. Once you click the toggle button, you should see a window identical to the one shown in Figure 2.
Figure 1: Toggle Button
Figure 2: Work Window
The next step is to fill in the information boxes at the head of the window. To do this, you will have to go to GitHub and go to “Developer Settings”. The path to get there is detailed below.
Profile Picture Menu > Settings > Developer Settings
Once there, you will need to create a Personal Access Token. The method necessary is detailed below.
Developer Settings > Personal Access Tokens > Tokens (classic) > Generate new token > Generate new token (classic)
Figure 6: Classic Token Sidebar Button
Figure 7: Generate New Token Dropdown
At this point, it is time to set the settings of your Personal Access Token. The GitSync plugin only requires that the repo scope be selected, like in Figure 8. After you finish naming your token, setting the expiration date, and selecting the scope, you should click the green “Generate Token” button at the bottom of the page (Figure 9). Finally, the last thing you need to do is copy your personal access token by clicking the “copy” button (Figure 10). Now, all you need is your repository!
Figure 8: New Token Settings
Figure 9: Generate Token Button
Figure 10: 'Copy Token' Button
When you are ready, paste your token and repository path in their corresponding text boxes in the plugin (Figure 11). Your repository path should be in the format of user/repository-name. For example, if my username is John and my repository name is potential-disco, then the repository path that I enter into the plugin would be John/potential-disco. These parameters save and persist across Studio sessions using plugin:SetSetting() after you enter or change them. This way, you don’t have to worry about saving your Personal Access Token or creating a new one every time you use the plugin! Once you have these values entered, you are ready to use the plugin!
Figure 11: Work Window with Values Entered
Pushing with GitSync is as easy as selecting the scripts you want to store/update and clicking a button. Specifically, the button shown in Figure 12. This button will turn green to indicate success and red to indicate failure. Make sure to check your output widget for important response information, especially if an error has occurred.
TIP - When selecting scripts to be pushed, don’t worry about the placement! Any Instance that is the ancestor of a Script, LocalScript, or ModuleScript will have its descendant scripts stored with the rest of the scripts.
Pushing uploads/updates your GitHub repository with a folder directory that runs all the way up to the name of the Place you are working in. When you pull your repository, this structure is maintained. To select the scripts that you want to push, CTRL + Click on scripts and script ancestors in the explorer (Figure 13). When you click on these, the scripts selected should be displayed in the work window (Figure 14). You can make sure your repository has been updated by using the built-in Repository Viewer, which is discussed later on (Figure 17).
Figure 12: Push Button
Figure 13: Scripts Selected in Explorer
Figure 14: Selected Scripts Displayed in Work Window
Pulling is even less complicated than pushing. When pulling, you have the choice to either:
- Select nothing and pull all your entire repository into Roblox Studio as a directory of folders and scripts
- Select specific scripts and have their Sources updated. The scripts in the repository that are not selected will still be imported, but they will not directly and instantly change the Source of a script.
Pulling using the second method is safest when there are no folders involved, and strongly advised against for the sake of preventing lost progress. As stated way above, Undo does not affect modifications made to a script’s source code. As a result, the best way to pull files is the first way: selecting nothing and clicking the pull button (Figure 15).
When you pull your repository, your scripts will populate the workspace (or the selected object) in a directory of folders that mimics the organization of the repository. When you push these files back to GitHub, try not to push them from inside the imported directory folders, because this will likely result in more nested, empty folders the next time you pull your repository.
Finally, every script is pulled and pushed with metadata attached (Figure 16). This can be observed in the form of the -- @ScriptType: ModuleScript/Script/LocalScript comment(s) at the top of your script(s). You are free to delete these comments on Roblox, but deleting these comments on GitHub will result in the script being pulled as a server-sided script rather than whatever class it was specified to be.
Figure 15: Pull Result of First Method
Figure 16: Metadata
The third and final taskbar button on the Work Window is that of the Repository Viewer (Figure 17). The Repository Viewer is like an explorer window for your repository. Using the Viewer, you can see everything in your repository, regardless of whether or not it’s a script! The Repository Viewer has live updates, which allow it to serve as proof that your files have been successfully pushed to GitHub (Figure 18).
Figure 17: Repository Viewer Button
Figure 18: Repository Viewer Before Pushing to GitHub
TIP - Clicking on files in the Repository Viewer opens a popup containing their Source code! If you click on the blue, bolded names that represent folders, you will open a new window inside the folder (Figure 19) !
Figure 19: Repository Viewer After Pushing to GitHub
At last, it is time for the settings button to shine (Figure 20) ! When you click the settings button, you will open the Settings Window (Figure 21). This window contains information about branches, which we will dive deeper into shortly. The Settings Window, just like the Work Window, can be closed by either clicking the button a second time or clicking the “Close Window” button (Figure 22) that I neglected to mention earlier.
Figure 20: Settings Button
Figure 21: Settings Window
Figure 22: 'Close Window' Button
In the Settings Window, we can manage our branches. Although there is currently no way to delete a branch, new branches can be created by typing any name that doesn’t already exist into the prompt (Figure 23). If you type in a name that is already taken, the plugin will switch to that branch. Otherwise, a new branch with the inserted name will be created and switched to. There are also buttons below the textbox prompt to streamline branch switching and minimize error (Figure 24). These buttons represent existing branches, and pressing one will automatically set your branch to the text shown in the button you just clicked.
Figure 23: Create/Set New Branch Prompt
Figure 24: Existing Branches List
All Field Guide Images
Figure 1: Toggle Button
Figure 2: Work Window
Figure 6: Classic Token Sidebar Button
Figure 7: Generate New Token Dropdown
Figure 8: New Token Settings
Figure 9: Generate Token Button
Figure 10: 'Copy Token' Button
Figure 11: Work Window with Values Entered
Figure 12: Push Button
Figure 13: Scripts Selected in Explorer
Figure 14: Selected Scripts Displayed in Work Window
Figure 15: Pull Result of First Method
Figure 16: Metadata
Figure 17: Repository Viewer Button
Figure 18: Repository Viewer Before Pushing to GitHub
Figure 19: Repository Viewer After Pushing to GitHub
Figure 20: Settings Button
Figure 21: Settings Window
Figure 22: 'Close Window' Button
Figure 23: Create/Set New Branch Prompt
Figure 24: Existing Branches List
All Tips and Warnings
TIP - When selecting scripts to be pushed, don’t worry about the placement! Any Instance that is the ancestor of a Script, LocalScript, or ModuleScript will have its descendant scripts stored with the rest of the scripts.
TIP - You can move the plugin windows by dragging them from the center with your mouse!
TIP - Clicking on files in the Repository Viewer opens a popup containing their Source code! If you click on the blue, bolded names that represent folders, you will open a new window inside the folder (Figure 19) !
Concerning the Usage of AI
(ChatGPT & Gemini were consulted in my creating this project. Don’t worry, they didn’t do that much work for me. I used them as guides when I didn’t know how to solve a problem and I couldn’t find a solution in any forum. If it eases your minds, it still took me forever to make this. Like, literally forever (ok I lied its impossible for it to take literally forever because I can’t live that long). You don’t have to worry about me missing the canon event of suffering through plugin development!)
.