GitHub Integration

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.

  1. Click the Settings icon and then click on GitHub.
  1. From the GitHub Integration page, click the Connect GitHub button.

This will redirect you to the GitHub's website.

  1. 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 sections and components to use as you build out your store. We will only use the write permissions for the Starter Kit update to your repo.

  1. 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:

  1. Once you go to the Settings>GitHub page, you will see that you are already connected as your GitHub user.
  1. 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:

  1. Click the Open GitHub button.
  1. Click on the Configure link of your installation.
  1. In the Repository Access section you can chose All repositories option or add the needed repository to the Only select repositories set. Click Save.
  1. Go back to the Settings>GitHub page. The added repositories will appear in the repository select, so you can choose the needed one.
  2. 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

The feature assumes that your code adheres to certain file paths and naming conventions.

  • A single component lives in src/components/<CamelCasedComponentName>

    • The code file is in src/components/<CamelCasedComponentName>/index.js
    • The CSS file is in src/components/<CamelCasedComponentName>/styles.css
  • A single section lives in src/sections/<CamelCasedSectionName>

    • The code file is in src/sections/<CamelCasedSectionName>/index.js
    • The CSS file is in src/sections/<CamelCasedSectionName/styles.css
  • Global styles are in src/global.css

  • Component and section names must match the folder name, which contains them i.e.

    const MyComponent = () => {
      return (
            // ....
      )
    }
    
    export default MyComponent
    

    MyComponent needs to be sourced from src/components/MyComponent/index.js

  • Section named PageMeta is 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 the src/sections/PageMeta/index.js file, the section won't be deleted from the site.

  • The index.js file 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.js and styles.css files in one commit.
    • If you want to remove a component (section), remove both index.js and styles.css in one commit.

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:

  1. Takes the latest code from the branch of the repository, configured for GitHub integration.
  2. 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:

  1. Go to Settings>GitHub.
  1. Click the Pull Code button. You will see a warning popup.
  1. 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.

  1. Go to Settings>GitHub
  1. 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.
  1. Click the Configure link next to your organization.

  2. In the Settings page, scroll down to the bottom until you see the Danger zone area.

  1. 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:

  1. 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.
  2. Click the Configure link next to your organization.
  3. In the Settings page, scroll down to the bottom into until you see the Danger zone box.
  1. 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:

  1. Go to Settings>GitHub to open the GitHub integration configuration page. Click the Open App button to open the configuration page.
  2. Click the Configure link next to your organization.
  3. In the Settings page, scroll down to the bottom until you see the Danger zone box.
  1. 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:

  1. Go to the Settings>GitHub page.
  2. Click the Connect GitHub button.
  1. You will be taken to the page with list of the GitHub accounts you have access to.
  1. Click the Configure link next to the account on which the GitHub app is installed.
  2. Click Uninstall button.
  1. 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.

Did this page help you?