Overview
The GitHub Integration is a feature which allows for automatic code syncing between your site repository and the Shogun Frontend application. It replaces the existing sync command by automatically pulling code changes from a pre-selected GitHub repository and a branch. As a replacement of the manual sync command, at the moment it has the same expectations about the code structure and what could be synced between the repository and the Shogun Frontend application. The feature currently supports syncing for:
Sections code
Sections style
Components code
Components style
Global styles
A few important high-level aspects regarding the feature are listed below:
The feature is called GitHub Integration for a reason — it currently only supports GitHub. We might be introducing support for other platforms in the future.
It is possible to link the same repository or different repositories in the same GitHub account to different sites that the frontend user has access to.
If multiple users have access to the same site, only the user who has set up the GitHub integration can modify the integration behavior.
It is not currently possible for a Shogun Frontend user having multiple GitHub accounts to link different stores they have access to, to repositories in different GitHub accounts.
Although a Shogun Frontend user may have access to different GitHub accounts and multiple sites, the user cannot integrate different sites with different GitHub accounts.
At the moment, there is no reporting or status updates whenever the Shogun Frontend application pulls code from the repository.
The assumption is that once you start using repositories for containing and modifying your store code, you are no longer relying on the IDE. If you make any code changes through the IDE, you would have to manually bring them in to the site repository. There is no true syncing between the Shogun Frontend application and the site repository.
Only Components (Sections) code contained inside JavaScript files and styles (including global styles) — contained inside CSS files — are being synced; using TypeScript or non-CSS styles would not work.
We don't currently have an export feature, so if you don't already have a repository with your site source code, you will need to manually copy code from the Shogun Frontend IDE into a repository, making sure to follow the format outlined in Conventions and Details.
Setting Up
Before setting up the feature, log into GitHub with an account which has access to the repository containing your store source code. The account must have owner privileges to the GitHub organization that owns the repository.
Click the Settings icon and then click on GitHub.
From the GitHub Integration page, click the Connect GitHub button.
This will redirect you to the GitHub's website.
If you're a member of one or more organizations in GitHub, you will be asked to select an organization:
After selecting an organization, select the repository containing your store code. You could select "All repositories", but this is not necessary and it is advisable that you select only the repository containing the site source code.
After clicking Install & Authorize, you will be redirected back to the Frontend application. Upon redirection you will see your github-username under Authorization & Open GitHub button to configure the connected GitHub account.
🚧 We ask for read and write permissions so that we can load the Starter Kit into your repository giving you a library of Components and Sections to use as you build out your store. We will only use the write permissions for the Starter Kit update to your repository.
4. If you want to load the Starter Kit into your account, please do not connect a repository and reach out to your Shogun point of contact. We will install the Starter Kit for you. If you connect a repository, it prevents us from easily installing the Starter Kit. You now need to select a repository and a branch. The branch will be monitored by the Shogun Frontend application: whenever new commits arrive, the code (Components, Sections and their styles) will get automatically pulled from the repository. The select input also includes a search feature to help users with a large number repositories and/or branches to quickly search the intended repository and a branch.
Once you select a repository and a branch, click on the Save button. The is the last step in the setup workflow. From now on every time a commit is made on the target branch (the one specified above), Shogun Frontend will automatically pull the latest version of the code.
Multi Site & Multi User Details
If you have access to multiple Shogun Frontend stores, you can set up GitHub Integration for any number of them.
📘 The only limitation is that the sites have to be connected to a single GitHub account. This will be resolved in upcoming releases.
Connecting multiple stores to GitHub
You just need to set up the integration for one of your stores, after that any other stores could use the already set up GitHub connection.
If you have already set up one of your stores:
Once you go to the Settings>GitHub page, you will see that you are already connected as your GitHub user.
In order to set up the integration you just need to select a repository and branch and hit "Save" button. The site integration is done.
If you don't see the needed repository in the repositories list, resolve by following these steps:
Click the Open GitHub button.
Click on the Configure link of your installation.
In the Repository Access section you can chose All repositories option or add the needed repository to the Only select repositories set. Click Save.
Go back to the Settings>GitHub page. The added repositories will appear in the repository select, so you can choose the needed one.
Go into each of your Shogun Frontend accounts and select what repository you want to connect to that store.
📘 Since you as a user authorized your user account, you will see the ability to connect all your Shogun Frontend stores to your GitHub repos. Other users will not see this since they have not authorized their Shogun Frontend account to Github.
When someone else set up integration for the site
If GitHub integration for the site had been set up by someone else, you won't be able to see the Open GitHub button and tweak any settings of the GitHub app, but you will still be able to edit repository and branch selection.
Conventions & Details
🚧 IMPORTANT
Nested directory structures are not supported. E.g., src/components/module1/MyComponent. Only src/components and src/sections folders will be synced with Shogun Frontend.
The feature assumes that your code adheres to certain file paths and naming conventions.
A single Component lives in
src/components/<PascalCasedComponentName>The code file is in
src/components/<PascalCasedComponentName>/index.jsThe CSS file is in
src/components/<PascalCasedComponentName>/styles.cssorsrc/components/<PascalCasedComponentName>/styles.module.cssif using CSS Modules.
A single Section lives in
src/sections/<PascalCasedSectionName>The code file is in
src/sections/<PascalCasedSectionName>/index.jsThe CSS file is in
src/sections/<PascalCasedSectionName/styles.cssorsrc/sections/<PascalCasedSectionName>/styles.module.cssif using CSS Modules.
Global styles are in
src/global.css
Component and Section names must match the folder name, which contains them i.e.
JSX
const MyComponent = () => {
return (
// ....
)
}
export default MyComponent
MyComponentneeds to be sourced fromsrc/components/MyComponent/index.js
Section named
PageMetais a special Section; it is synced with the repository as any other Section, but it is protected from removal. That means that even if you remove thesrc/sections/PageMeta/index.jsfile, the Section won't be deleted from the site.
The
index.jsfile within each Component (Section) is considered the main file of the component - when you add or remove this file, the corresponding component will be added or removed respectively. The code changes are synchronized on a per commit basis, so in order to avoid possible inconsistencies, please follow the following guidelines:If you want to introduce a new Component (Section), create both
index.jsandstyles.css(styles.module.css) files in one commit.
Naming conventions
Non-alphanumeric characters are stripped out.
Dashes and spaces are replaced with an underscore. Multiple consecutive dashes and spaces are replaced with one underscore.
Pull Code
Once GitHub integration is set up, it works by looking for changes in the selected branch of the repository. When it sees that the branch was updated with new code, it syncs that change with your site automatically.
But in some situations you may want to manually sync your site with your repository, to be 100% sure that your store is in-sync with the repository. These situations can be:
You've set up GitHub integration for a site and connected a repository that already has some code you would like to be synced.
When you check you store, you don't see the updates that you made in your repository.
You just want to make sure that your site got all the latest code from the repository.
The Pull Code feature works as follows:
Takes the latest code from the branch of the repository, configured for GitHub integration.
Updates the site's code with code obtained in the previous step. The existing site code will be overwritten, so if you made changes in the IDE, they will be lost.
Code pulling is using same conventions and details as regular GitHub integration syncing.
In order to pull code, you need:
Go to Settings>GitHub.
Click the Pull Code button. You will see a warning popup.
If you wish to proceed, click the Force Pull button. The site's code will be updated shortly; meanwhile, you can leave the page.
Suspending
If you would like to temporarily suspend the behavior of the feature (stop processing commits on the target branch), you can do that by following the steps below.
Go to Settings>GitHub
Click on the Open App button. It would take you to the GitHub settings page for Shogun Frontend if you have a valid GitHub session. In case your account has access to multiple organizations, you would see a screen similar to the one below first.
Click the Configure link next to your organization.
In the Settings page, scroll down to the bottom until you see the Danger zone area.
Click the Suspend button.
The GitHub Integration is now suspended. While suspended, it does not have access to your GitHub resources and will not be able to update code and styles in Frontend.
Unsuspend
To resume the GitHub integration so that updates automatically sync with Shogun Frontend again:
Go to Settings>GitHub to open the GitHub Integration Settings page. Click the Open App button to open the Shogun Frontend GitHub integration configuration page.
Click the Configure link next to your organization.
In the Settings page, scroll down to the bottom into until you see the Danger zone box.
Click the Unsuspend button.
The GitHub integration is no longer suspended. Changes to your configured repository and branch will again automatically be synced to Frontend.
Uninstalling
To uninstall the GitHub integration:
Go to Settings>GitHub to open the GitHub integration configuration page. Click the Open App button to open the configuration page.
Click the Configure link next to your organization.
In the Settings page, scroll down to the bottom until you see the Danger zone box.
Click the Uninstall button.
The GitHub integration feature is no longer working. In order to enable it again, you would have to follow the initial steps outlined in this guide.
Migration to the new GitHub Integration version
Migration to the new GitHub Integration version requires the integration to be re-installed. The following steps explain how to do that:
Go to the Settings>GitHub page.
Click the Connect GitHub button.
You will be taken to the page with list of the GitHub accounts you have access to.
Click the Configure link next to the account on which the GitHub app is installed.
Click Uninstall button.
If you have more than one account where the GitHub app is installed, as shown in the step 3 screenshot, you will need to return to the Settings>GitHub page and repeat steps 4 and 5 for all accounts.