Sharing your Salesforce App on Github

Tweet

Sharing your Salesforce App on Github

Introduction

Over the years there’s been a few ways to give away Salesforce apps. When I first started 10 years ago there was a Google Code Share accessible from the Developerforce site, but that star waned some time ago. There’s also unmanaged packages, but that typically requires someone to install your package into an org before they can look at the contents of the app, which is fine if they know they want to use it in it’s entirety, but less useful if they want to use your app as s starting point or example for something that they are doing.

Over the last few years, Github has become the de-facto way to share and collaborate on code. As well as providing (free for public) Git repository hosting, it has a bunch of other cool features to allow people to collaborate:

• Pull requests, to allow changes to be reviewed, discussed and refined before they are merged.
• Issue tracking, to capture ideas, feature requests, bugs
• Releases, so that you can wrap and ship specific versions

A collection of useful applications in Github is also a signal to potential employers that you are passionate about app creation and I’m sure won’t do your career any harm. It’s also a great way to share a sample application after presenting at a user group or World Tour event.

I’m using my Summer 18 samples codebase as the example Salesforce application for this post. Note that this post assumes you have created a Github account and completed Git setup.

But Github is Microsoft now

It is, but under Satya Nadella we’re seeing a new Microsoft, particularly around open source. Even if you are nervous around what might happen to Github in the future, you are putting your application out there for everyone to use, so it’s not like it’s some big secret that Microsoft might help themselves to. I can see how a Microsoft competitor with a business account might be worried about security,  but for public applications it’s not something I’d be concerning myself with.

Metadata

The most common mechanism of storing an application outside of Salesforce is extracting the metadata via the Metadata API (SalesforceDX Scratch Org format is the new kid on the block, but at the moment is more likely to be of interest to ISVs in my opinion). There are various mechanisms for extracting metadata, requiring various degrees of setup, such as:

• An IDE, such as the Force.com IDE, where you can choose from a subset of metadata to retrieve
• The Force.com Migration Tool (ant), where you’ll need to define a manifest file (package.xml) describing the metadata you want to retrieve
• The Salesforce CLI, via the force:mdapi:retrieve subcommand - again you’ll need a manifest file
• The Force.com CLI, via the export and fetch commands.

In my view the Force.com CLI is still the easiest tool to use to export metadata - I wrote a blog post explaining how to do this a while ago.

Once you have your metadata exported you will have a structure similar to the following:

 

Creating a Local Repository

Github uses Git to manage the set of files that make up your application, stored in a data structure known as a repository. This enables tracking of changes to files (and much more besides). In order to create a repository, however, you need to extract your application from Salesforce.

Once your metadata is extracted from Salesforce it’s in a state where you can easily migrate it to other orgs, but it isn’t set up to be managed by Git. To turn your codebase into a local Git repository, you use the git init command:

$ git init .

Initialized empty Git repository in /Users/kbowden/GithubBlog/.git/

You can then run git status and see that you have indeed turned your app into a repository:

$ git status 

On branch master 
No commits yet 
Untracked files:

  (use "git add ..." to include in what will be committed)

       src/ 

nothing added to commit but untracked files present (use "git add" to track)

So you have a repository, but none of your applications files are being tracked by it. To achieve this, execute git add to stage the files and then git commit to commit them to the repository:

$ git add src

$ git commit
[master (root-commit) 35fa327] Created.
 31 files changed, 202 insertions(+)
 create mode 100644 src/aura/Navigator/Navigator.auradoc
 create mode 100644 src/aura/Navigator/Navigator.cmp

      ...

 create mode 100644 src/classes/UtilityController.cls
 create mode 100644 src/classes/UtilityController.cls-meta.xml

Note that the git commit command will open an editor for your commit message.

Create the Remote Repository

Now that the code is being tracked by Git, the final step is to create the remote Github repository and push your local changes to it.

There are various ways to set up a remote repository, I use the following steps as it reminds me to set up the README.md file that serves as the “home page” for the repository on Github:

1. Login to Github
2. Click the + button on the top right and on the resulting dropdown menu, select New Repository
   
   
3. Fill out the resulting form, making sure to tick the box titled 'Initialize this repository with a README’, and click the Create Repository button
   
   
   
   
4. On the resulting page, click the ‘Clone or Download’ button and copy the Web URL:
   
   
   
   
5. Add the remote repository, using the Web URL copied in the step above. I’ve named the remote ‘origin’ as this is going to be the main repository going forward:
   

   $ git remote add origin https://github.com/keirbowden/GithubBlog.git

6. Verify the remote:
   

   $ git remote -v
   
   origin https://github.com/keirbowden/GithubBlog.git (fetch)
   origin https://github.com/keirbowden/GithubBlog.git (push)

Pushing Local to Remote

The remote Github repository is now created and associated with the local repository. There’s nothing in the remote repository apart from the README.md file, so the next step is to push the contents of the local repository. Before this can be done, the contents of the remote repository must be merged in, as it has changes (README.md) that aren’t in the local repo.

The git pull command fetches the changes from the remote repository and merges them into the named branch in a single action. As the local and the remote repository have been created separately, use the '--allow-unrelated-histories' option to allow everything to be coerced into a single set of files:

$ git pull origin master --allow-unrelated-histories

  From https://github.com/keirbowden/GithubBlog
   * branch master -> FETCH_HEAD
  Merge made by the 'recursive' strategy.
   README.md | 2 ++
   1 file changed, 2 insertions(+)
   create mode 100644 README.md

Finally, push the consolidated repository to Github via the git push command:

$ git push origin master

  Counting objects: 30, done.
  Delta compression using up to 8 threads.
  Compressing objects: 100% (24/24), done.
  Writing objects: 100% (30/30), 4.71 KiB | 1.57 MiB/s, done.
  Total 30 (delta 2), reused 0 (delta 0)
  remote: Resolving deltas: 100% (2/2), done.
  To https://github.com/keirbowden/GithubBlog.git
   f956682..be01baf master -> master

All Done

Accessing the repository on Github shows the entire Salesforce application is now available:

Related Posts

• Force CLI Part 2 - Extracting Metadata
• SFDX and the Metadata API

 Follow @bob_buzzard