Source control your Salesforce metadata with GitHub Enterprise and Gearset
Matt Dickens on September 29th 2016
tl;dr: Deploy metadata directly to and from GitHub Enterprise with Gearset. Read on to find out how to get started!
When making the decision to version control your metadata, one of the first things you’ll need to figure out is where to host it. There are a variety of great options out there, but one of the first that’s likely to cross your mind is GitHub. Its ubiquity in the open source community and beyond not only means that it’s an incredibly well-documented platform supporting robustly exercised collaboration workflows, but it also means that most developers you meet will have certainly heard of GitHub and probably used it; the term “pull request” has entered into everyday developer parlance.
So GitHub’s a great choice for developer collaboration and hosted version control, and the good news is that Gearset already supports seamless integration with it. Unfortunately, having your source code hosted by a third party on servers that aren’t under your direct control can be prohibitive for some businesses, particularly in verticals like healthcare or finance where compliance is paramount.
Thankfully, GitHub Enterprise has you covered. In short, GitHub Enterprise (GHE) gives you all the functionality of GitHub packaged for convenient deployment to infrastructure under your direct control, on either AWS, Azure, or your own on-prem hardware.
Connecting Gearset and GitHub Enterprise
Today we’re releasing integration between Gearset and GitHub Enterprise. After setting up a GHE connection, you’ll be able to use all the functionality of Gearset’s GitHub integration with your GHE instance.
Step 1: Creating an OAuth app in GHE
To get started, you’ll first need to create an OAuth app in your GitHub Enterprise instance - this will let Gearset use OAuth to authorize against and talk to your GHE instance.
First sign in to GHE and navigate to the **Settings** page, then **OAuth applications**
From here, click the **Developer applications** tab and click **Register a new application**:
You’ll need to fill in the settings - the **Authorization callback URL** needs to match the value below. Once you've filled in the settings click **Register application**:
- Application name: Gearset
- Homepage URL (optional): https://gearset.com
- Authorization callback URL: https://app.gearset.com/authorization/github-enterprise/callback
Once that’s done, you’ll see a summary of the application, including a Client ID and Client Secret. These values, combined with the URL of your GHE instance, are what you’ll need to get Gearset and GHE talking to each other:
Step 2: Connecting Gearset to GHE
All that remains is to pass the information from the last step above to Gearset.
Navigate to the Manage orgs page in Gearset, and click Connect to GitHub Enterprise:
In the resulting dialog, enter your GHE URL and the client ID and secret of your OAuth app from step 4 in the previous section, and click Connect:
This will initiate the OAuth flow and navigate you to GHE where you’ll be asked to approve Gearset’s access to your repositories.
And that’s all there is to it! If you navigate back to Compare and deploy, pick Source control as your metadata location and pick GitHub Enterprise as your source control type, you’ll find your GitHub Enterprise repos.
Coming soon: deploy straight from your Salesforce org to GitHub
What we’ve shown so far will let you deploy directly from GitHub Enterprise to your Salesforce orgs. But what about getting the metadata from your orgs back into GitHub? The usual practise here is to use the Force.com migration toolkit, Eclipse, MavensMate, or one of a variety of other tools out there to pull your metadata to your local disk. From there, you can use your git client and workflow of choice to push those changes back to source control.
This is, of course, a very flexible process - you’re free to use the tools and methodologies of your choosing. Unfortunately, this process still requires a degree of manual and potentially error-prone work - we can definitely go further towards automating the mechanical steps.
With that in mind, we’re currently running a private alpha that allows you to deploy straight from your Salesforce org to a git repository and branch of your choosing. We’re expecting to release this to a wider audience shortly after Dreamforce, and we’ll follow up with a more detailed blog post at the time. In the meantime, here’s a brief demo to whet your appetite:
That covers it for this time - source controlling your Salesforce org metadata with GitHub Enterprise is now easier than ever before! If you have any feedback on what we've shown here then don't hesitate to reach out to the team at [email protected], or leave us a message via the chat widget!