Getting Started with Git

The Cascade system manages source code using an integrated and hosted per-client instance of GitLab CE. This means that some foundational knowledge of how to interact with a Git repository is required for success in deploying code on the platform.

This quote from the official Git documentation site https://git-scm.com/ describes Git very well:

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.

Git is easy to learn and has a tiny footprint with lightning fast performance. It outclasses SCM tools like Subversion, CVS, Perforce, and ClearCase with features like cheap local branching, convenient staging areas, and multiple workflows.

We are confident that these resources will get you started on a path to success with deploying your code on Cascade systems.

Installing Git

In order to use Git on most systems a command line client will need to be installed. Though graphical clients for Git are available for some system, the Git community overwhelmingly recommends beginning users first learn the core concepts using the command line client.

Git is widely available for Macintosh, Widows, and Linux workstations. We recommend installing with the sources identified by the official documentation site: https://git-scm.com/downloads

After you have a working git client, pushing code to a Cascade GitLab instance requires setting up either an account password or an ssh key.

Authenticating for GitLab Repository Access

To make changes to the codebase connected to a given Cascade project you will need to add additional authentication details to your GitLab account. The options available to connect are via http(s) or ssh.

Add your SSH Key to Gitlab

The basic steps to add your SSH key to GitLab are:

  1. Log into Cascade.

  2. Navigate to the platform GitLab instance.

  3. Click the User Account drop-down at the top right, and select “Edit Profile” from the available options.

  4. In the left side toolbar, find the SSH Keys section and click it to open the section.

  5. Paste the public SSH key you would like to use into the form, give it a good name, and click the “Add key” button to add it to your account.

More detailed instructions with steps for locating and manging compatible SSH keys for supported systems is available at the GitLab documentation site: https://docs.gitlab.com/ee/ssh/index.html

Create a GitLab Personal Access Token

If you need to use https authentication or have trouble creating and maintaining an ssh key we suggest adding a personal access token to your GitLab account.

The basic steps to create a personal access token in GitLab are:

  1. Log into Cascade.

  2. Navigate to the platform GitLab instance.

    • There is a link to GitLab at the top of every page.

    • The URL is going to be of the form https://[ID]-gitlab.ab.contegix.com and the page should look similar to the following screenshot:

      GitLab add password form

  3. Click the User Account drop-down at the top right, and select “Edit Profile” from the available options.

  4. In the left side toolbar, find the Access Tokens section and click it to open the section.

  5. Fill in a name, expiration, and access control features of your choice. We expect you will probably need at least read_repository and write_repository permissions.

  6. Click the “Create personal access token” button to generate the token. The password for the token will be shown once at the top of the form, remember to save it securely for later use whenever a password is called for in git operations.

More detailed information about how to create and use Personal Access Tokens is available on the official GitLab documentation site: https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html

Developing Locally

After setting up your workstation with tooling for developing your software, one of the first things you will need is a copy of the source code for your project. As a distributed revision control system, Git is capable of synchronizing with many disparate systems, and to connect with these systems you will need a URI in the given format you setup in the previous section. If you would like to synchronize with the systems controlled by Cascade, follow these steps:

  1. Install Git CLI client

  2. Gather the URI to connect the local copy to a remote. The most convenient way to find the git URI for a Cascade project is to navigate to the project within Cascade and click on the “View Source Code” link near the top of page content; this link targets the project landing page in Gitlab. On that GitLab page there is a button labeled “Clone” after the operation you would perform, clicking that clone button will display options for ssh and https endpoints. See the screenshot below for an example:

    GitLab project clone options

  3. Open a CLI terminal and change your working directory to where you would like place the code. This is typically a location connected to a local web application service, but, it can be anywhere in your workstation file system.

  4. Clone the project to your workstation using Git CLI commands. Examples:

    • SSH (preferred): git clone git@abdev-id.ab.contegix.com:drupal7example/drupal7example.git
    • HTTPS: git clone http://id-gitlab.ab.contegix.com/drupal7example/drupal7example.git

For more information about cloning GitLab repositories:

Committing your Code

Below are general tasks that are common to every software development workflow no matter what tools are involved. The entries on the list are followed by a dash and the Git tasks often used to accomplish the task.

  1. Acquire a new copy of the code - clone
  2. Start working on something - branch, checkout
  3. Save your changes - add, commit
  4. Share your changes with others - push
  5. Update your copy with new changes from others - pull
  6. Integrate changes with others - merge
  7. View what has changed - status, history

If you are entirely new to Git, we have found that learning the GitHub flow model is a great way to start understanding how to work with others. This model is also directly applicable to GitLab (where they call it GitLab flow).

Deploying Changes to Cascade Environments

Cascade is integrated with the GitLab instance provided to by the platform to automatically detect and deploy changes. Cascade automatically deploys a project by watching for GitLab API notifications of commits being made in branches it has been configured watch in each GitLab project.

You can discover which branches Cascade is watching for changes on by looking at the code configuration section in every project. To find this configuration, navigate to a project dashboard and click the code icon (Open the code settings).

The watched branches are configurable on a per-project basis and are named according to the needs at hand. Most projects we encounter follow one of the following deployment methodologies:

  • Tag-based: The primary branch, typically master or main, is shared amongst all environments. In the typical Cascade configuration to support this setup, the main/master branch is wired up to the development environment and commits to main/master branch are automatically deployed to development when they are pushed to the GitLab instance. Deployments to production and other environments are handled via button click in the Cascade UI only.
  • Branch-based: Each environment has its own branch that is being watched for changes. Deployments to each environment are triggered automatically by commits to the associated branch via Git or the Cascade UI Merge button click. In most Cascade configurations for this setup, the branches Cascade is listening to are named with the target environment as part of branch name.

For projects that do not fall into one of the above methodologies, there is some hybridization of the models available provided the workflow starts in branch-based mode and completes in tag-based mode. Remember that you can always decide what branch or tag is deployed to a particular environment by adjusting the project configuration manually.

If you have not yet, read more about code considerations in the Add a New Project guide.