Bubble integrates with GitHub so that you can save a version of your plugin in a repository and benefit from Git's version control features.

The primary data store remains Bubble's servers, and what you have on GitHub is a copy of the plugin.

If you modify the code on GitHub (see below), you'll be able to fetch the latest commits back into Bubble's storage.

Connecting with GitHub

This button will only be shown if you have already published a marketplace item or are registered as a seller. If you are developing a free plugin, you won't be able to sync with GitHub until one of these conditions is met.

The first step is to link your Bubble and GitHub accounts. If you used GitHub to sign up, you're all set. Otherwise, you can link your account in the Account > Marketplace > Settings page (you'll need to register as a seller on Stripe first to access the Marketplace Settings tab).

Once this is done, you'll be able to use the GitHub section in the Version Tab of the Plugin Editor.

Synchronizing with GitHub

First synchronization

The first time you hit 'Synchronize with GitHub', a new repository will be created in your GitHub account. Bubble will generate a repository name based on the plugin name you've defined in the General Tab. By default, Bubble will attempt to create a private repository. If you are not on a paid GitHub plan, the operation will fail — but if you make your plugin open source, you'll be able to create a public repo under the MIT license.

Note that if you delete the repository in GitHub, the connection will be reset and the next synchronization will behave like a first sync. A new repository will be created.

Subsequent synchronizations

Once the connection is set up, you can regularly synchronize with GitHub. When you do, a few situations can occur:

The version in Bubble's storage (the one in the Editor) is ahead of the current commit. This means you've modified the plugin in Bubble since your last synchronization and haven't committed anything directly in GitHub. The newer version will be pushed to Git with an automated commit message.
You've modified the plugin in GitHub (for instance by merging a pull request) and haven't modified the version in Bubble. The new version will be fetched from GitHub and you'll be able to work from it.
Both versions (in Bubble and GitHub) have been modified, with a new commit in GitHub, and the changes can be successfully merged with Bubble's version. The synchronization will merge and pull the latest version from GitHub to Bubble.
Both versions are modified and there are conflicts. The version in Bubble will not be modified, and a pull request will be created in your repo. You can then work on the merge, resolve conflicts, and pull into the main branch. Once done, the next synchronization will fetch the conflict-free version to Bubble.

Tip: If the linked GitHub repo is moved or deleted, that will confuse Bubble's plugin editor. If you find yourself unable to restore access, please reach out to our Success team, who will be happy to look into it for you.

Forking plugins

One of the key benefits of GitHub integration is that you can fork published open source plugins, provided the author is also using GitHub. If that's the case, a button will appear to fork the plugin into your account. This will copy the plugin, fork the Git repository, and synchronize the new plugin with the new repository. You can then work on your plugin normally and use GitHub's native forking features when collaborating with the original author.

Folder & code structure

When a plugin is synchronized with a Git repository, the entire data is synchronized in a structured manner. When you modify the plugin in GitHub, in another code editor, or by merging someone else's changes, it's recommended to keep the structure identical. Here's how a plugin's code and data is organized.

File formats

Data and code can be represented as JSON, JavaScript, or HTML files. HTML headers injected into pages will be HTML files. Code for elements and actions will be in JavaScript. Everything else is represented as a JSON file and is what you can modify through Bubble's UI. Be careful when modifying JSON files — some changes can make the files unreadable by Bubble.

Folder structure

The folders follow the architecture of the Plugin Editor. What's in the Shared Tech Tab is at the root level, while API calls, elements, and actions are in three separate folders. The API definition is one major JSON file, while elements and actions are separated into sub-folders.

IDs

When navigating the folders, you'll notice some keys in the JSON files that are unique IDs (such as 'AED'). These apply to elements, API parameters, etc. Do not modify these entries — they are used in users' apps to represent the different items. You can, however, safely modify captions and similar fields.