SPGo was designed from the beginning to be a code-first and source-first tool for building SharePoint web solutions. Below are outlines for two common delivery scenarios: The first example shows how to use GitHub repo for one or more developers with their own SharePoint development environments. The second describes a collaborative approach where two ore more developers share a single SharePoint environment. Github usage is very similar across both of these scenarios, with configuration management (spgo.json) being the key differentiator.

This is not a general GitHub tutorial, but there may be opinions ahead!

Solo Development Environment

In this scenario we have:

  • A single, Shared Github repo
  • Multiple development environments - one for each developer
  • Possibly multiple SharePoint farms
  • Multiple spgo.json configuration files

Getting Started with a Solo Project

To start a new project, a new repo on GitHub should be initialized. Once the repo has been initialized, each developer will issue a git pull command to get the latest from the current development branch (or create a new development branch) to a folder on their local machine. From there, the developer will open the root project folder, created by git, in VSCode and run the SPGO> Configure Workspace command to initialize the spgo.json configuration file. Remember to point to your specific development environment when specifying the sharePointSiteUrl

Major Difference: When working with individual development environments, it is recommended that you add an entry for spgo.json to your .gitignore file. This will prevent your local site configuration from conflicting with other developers. As a scalable approach, you should add an example spgo.json file to the repo’s readme.md file so that developers can quickly amend their local config to match shared entries that the team will use.

Building Features with a Solo Project

If the SPGo project has already been initialized, you should have a basic folder structure in place. From here, development is pretty standard. Build your solution using SPGo, verify your changes in your development SharePoint environment and then commit your code to GitHub when the feature has been tested and is ready for QA/Customer sign-off.

Example spgo.json Config with a Solo Project

{
    "sourceDirectory": "src",
    "sharePointSiteUrl": "https://tennant.sharepoint.com/sites/myDevSite",
    "publishingScope": "SaveOnly",
    "authenticationType": "Digest",
    "remoteFolders": [
        "/siteassets/**/*",
        "/_catalogs/Masterpage/*",
        "/_catalogs/wp/*"
    ]
}

note: publishingScope can be set to Major or Minor for any site with Publishing enabled, allowing non-administrator users to view changes.

Collaborating in a Shared Environment

In this scenario we have:

  • A single, shared, Github repo
  • A single development or integration environment, shared across all developers
  • A single, shared, spgo.json config file.

Getting Started in a Shared Environment

To start a new project, a new repo on GitHub should be initialized. Once the repo has been initialized, each developer will issue a git pull command to get the latest from the current development branch (or create a new development branch) to a folder on their local machine. From there, the developer will open the root project folder, created by git, in VSCode and run the SPGO> Configure Workspace command to initialize the spgo.json configuration file. Remember to point to your shared integration environment when specifying the sharePointSiteUrl. In this scenario all developers

Major Difference: When working in a shared environment, it is a strong recommendation that you always use SharePoint’s publishing infrastructure to ensure that conflicts are minimized. SPGo will automatically detect changes between your local file and the server file when you issue the SPGO> Check out File command and present you with the VSCode compare window. GitHub will act as a secondary control to prevent conflicting changes from overwriting each other when committing code.

Building Features in a Shared Environment

If the SPGo project has already been initialized, you should have a basic folder structure in place. From here, development is pretty standard. Build your solution using SPGo, verify your changes in your shared environment and then commit your code to GitHub when the feature has been tested and is ready for QA/Customer sign-off.

Example spgo.json Config for a Shared Environment

{
    "sourceDirectory": "src",
    "sharePointSiteUrl": "https://tennant.sharepoint.com",
    "publishingScope": "Major",
    "authenticationType": "Digest",
    "remoteFolders": [
        "/siteassets/**/*",
        "/_catalogs/Masterpage/*",
        "/_catalogs/wp/*"
    ]
}

recommendation: it may be easier for a single developer to initialize the repo and create a base spgo.json file. This will ensure that everyone on the team has the same config, file hierarchy, and will minimize the chance of ending up in merge-hell.

Further Reading

For multi-stage environments, such as dev->test->prod, please see: SPGo and SDLC