Skip to main content

Using GitHub for Managing Site Assets

  • Updated

A mix of front-end and application developers frequently need to collaborate on projects. One of the areas that can result in overwriting each other is working with the assets that control the styling and behavior, aka CSS and JS.

The following instructions assume that all your site-specific assets for the overall look-and-feel of a project will be stored under the assets/theme/ directory for the project. Under this directory there will be a css/, js/ and img/ directories, containing those files as needed.

In practice, your projects will likely look very different. But in general it is easier to isolate your source-controlled files in a single directory, so you don’t have to worry about .gitignore files, conflicts, and mixing source-controlled and installed assets.

Setup a Deployment Key at GitHub

  1. Connect to your instance via SSH using the MODX Cloud SSH password or via SSH keypairs
  2. Add public keys for your collaborators to make it easy to connect to your instance.
  3. Create an SSH keypair to use  for a Deployment Key at GitHub, using an actual email address:
    cd ~/.ssh
ssh-keygen -t rsa -b 4096 -C "user@example.com"
  4. When prompted for the key name, just stick with the default id_rsa. If you want to make a custom one like "github_id_rsa" then just enter that and don't worry about entering the full path.
  5. Copy the public key to your clipboard by using the command cat id_rsa.pub to show the full public key in your terminal. Use your mouse to select the full public key and copy it to your clipboard. 
  6. Log in to your repository at GitHub, and navigate to your https://github.com/account/repository/settings/keys page.
  7. Click the add deployment key button in the upper right, give it a name, and paste in your copied public key into the appropriate text box.

Add the Site Assets to the GitHub Repo

Commit the files and directories that will reside in the assets/theme/ directory using your favorite Git tool. The top level in the example scenario above should just contain only the three folders and any other files inside them of course (though you can use any structure you need for your project):

  • css/
  • js/
  • img/

Clone the Project from GitHub

For this step, you need two pieces of information: your GitHub repository name and the intended destination directory name.

The reason you do not need to use your GitHub login or account to authenticate is that you have previously installed the deployment key per the above, which automagically handles this for you.

For this example, we'll assume the following:

  • GitHub repo in your account: my-awesome-project
  • Destination directory: site (which is found under assets/, per the above)

Now we can checkout the project using the above information:

  1. Connect to your instance via SSH, per step 1 above
  2. Change to the intended parent directory that your collaborators will be working in:
    cd /www/assets/
  3. Checkout the GitHub repo into the required (but not yet existing) theme/ directory: 
    git clone git@github.com:/my-awesome-project.git theme/

Update Site Assets Using GitHub

Now you're ready to use Git to manage your project. Each collaborator should checkout and modify the site assets in their local environments. When they're ready to promote those assets to the project, they commit them per standard Git practices.

To update to the latest version of the assets for your site from GitHub, do the following:

  1. Connect to your instance via SSH, per the above
  2. Change into the source-controlled directory inside your webroot where your site’s theme assets reside. Note that we're going to the full "theme" directory this time:
    cd /www/assets/theme/
  3. Pull the latest version of the assets from the GitHub repository: 
    git pull

     

Related articles