Sharing Contributions with Forge Rock via Git Subtree

The Radius Server functionality has raised interest in the community and is desired as a feature of Open AM. At the same time there is more to do on the feature set such as adding attribute mapping. Currently, the final success response is a simple Access-Accept response with no fields included as can be seen in that former post. So as work progresses I'd like to be able to do that in my local and on-premis remote repos and when ready with a new feature be able to push those changes as a unit to be included in baseline via an external remote repo.

But that goal is further complicated by how we are currently including Open AM and injecting extensions that we need.

Project Directory Structure

Our approach is to use maven's war overlay plugin as one maven subproject in a larger parent project and have siblings along side it representing separately build-able pieces that replace chunks of Open AM such as the openam-auth-radius maven submodule that we've extended to add the Radius Server functionality. Our project directory structure looks like this:

The root maven project is the top level openam folder. I'll cover the relevant parts beneath that directory. The openam-authentication directory is a maven subproject mirroring Open AM's corresponding submodule. Within this module are two authentication submodules one being openam-auth-radius that contains the original Open AM code with our enhancements. The openam-auth-smsotp is a One Time Passcode authentication module that delivers via an in-house REST SMS service and includes support for both HTTP and Radius clients allowing us to do multi-factor authentication for VPN access as well as web sites.

The openam-extensions includes extension point implementations such as a post authentication processor enabling us to front our older Oracle Access Manager system with Open AM, some custom tag libs for help in skinning the sign-in page, and other supporting runtime code.

The openam-warOverlay directory is a maven submodule that has the magic for pulling in the version of Open AM that we build against (12.0.0 currently) and including the other modules mentioned openam-extensions, openam-auth-smsotp, and openam-auth-radius replacing the corresponding jar where applicable in the Radius case.

Sharing That One Directory

The goal is to share the openam-auth-radius directory with a separate and off-premise Git repo while maintaining a local copy of the code to be worked on as needed and then selectively push enhancements to the external repo only when we have a fully functional feature to contribute. But I need to do this with an existing directory structure. I researched both Git submodules and Git subtrees and felt the latter were the better approach since all members of our internal team would just get the codebase when they clone without having to take steps to pull in the Git submodules themselves.

The steps found here looked exactly like what I needed. The steps that I took follow. In case that other page goes away I'm adding comments here for my reference when I have to do this again.

Extract the Directory as a Git Subtree

First I pull that directory's code out of the project by making an empty Git repo and pushing the current code to it. I created the radius-contrib directory as a sibling to the openam directory but it really could be anywhere outside of an existing Git project.

mkdir ~/git/radius-contrib
cd radius-contrib
git init --bare

Back in the openam project root directory I create a Git subtree by splitting out the openam-auth-radius subdirectory and creating a branch called contribs holding just that directory's code:

git subtree split --prefix=openam-authentication/openam-auth-radius -b contribs

Be forwarned, that step freaked me out a bit as it started dumping the following lines before indicating that the subtree was created. I don't know what they mean but it appears to be part of the process.

-n 1/     104 (0)
-n 2/     104 (1)
-n 3/     104 (2)
...
-n 102/     104 (101)
-n 103/     104 (102)
-n 104/     104 (103)
Created branch 'contribs'
2c4608649741ce14ce09e21bd766681bf6d219f3

Now I push that into my recently created empty repository. To do this I must be sitting in the newly create subtree otherwise you get messages like:

error: src refspec constribs does not match any.
error: failed to push some refs to '/Users/boydmr/git/radius-contrib/'

So change directory as needed and then do the push:

cd ~/git/openam/openam-authentication/openam-auth-radius
git push ~/git/radius-contrib/ contribs:master

Now moving into the directory of the newly created Git repo I can now see the newly created master branch that resulted from that step:

git branch -a
* master

Now we can push just that directory into the external remote repo:

git remote add origin https://github.com/...<fill-in-your-repo>

git push -u origin master

Once pushed that remote repo contains everything that resides within the openam-auth-radius directory and its subdirectories but not the openam-auth-radius directory itself. That is all for today. In my next post I'll take the next steps to now pull that repo into my subtree and even make some changes and push them back.

See you then.