Version control for SDLC

The Software Development Lifecycle, or SDLC, is the process of iterating on the design, development, and testing of software. Instabase provides tooling to assist you in using SDLC processes.

Warning

The Instabase SDLC feature is in long-term support (LTS). We will fix any critical bugs, but there will not be any further feature development.

Instabase provides a means for versioning Instabase files to an external Git repository, allowing multiple users to collaborate on the same set of files. Users can create a new Git repo to sync a particular folder in a Subspace; another user can then also sync a folder in their Subspace with the Git repo and commit new changes.

Instabase supports several Git providers:

  • Github

  • Gitlab (community and server edition)

  • Bitbucket (server edition only)

  • Azure Dev Ops

In this guide, we will introduce the use of the SDLC panel, which allows you to version projects on Instabase.

By the end of this guide, you should be able to:

  • Create a project with versions managed on GitHub, GitLab, Azure Devops or BitBucket Server

  • Pull and push versions for a project

  • View the current status of your local project compared against the latest remote version

Prerequisites

For this exercise, you need an access token for your user on the external Git Provider (GitHub, GitLab or BitBucker Server). Instabase manages versions of a project using the Git Provider. The remote project will be saved as a repo owned by the user for that access token.

  • To create a personal access token on GitHub, follow the instructions for Creating a personal access token for the command line. The token should have the following scopes enabled:

    • Repo

    • read:user

  • To create a personal access token on GitLab, follow the GitLab instructions for Creating a personal access token. The token should have the following scopes enabled:

    • api

    • read_user

    • read_repository

    • write_repository

  • To create a personal access token on BitBucket Server, follow the instructions for Creating a personal access token. To use the generated token in an SDLC project, the required format is bitbucket_username:token.

    • To connect to an existing repository on Bitbucket Server, the token should have the following scopes enabled:

      • Repository Write

      • Project Write

    • To enable creation of a new repository from the Instabase Platform, the token should have the following scopes enabled:

      • Repository Admin

      • Project Admin

  • To create a personal access token on Azure Devops, follow the instructions for Creating a personal access token. To use the generated token in an SDLC project, the required format is organization_name:token. The token should have the following scopes enabled

    • Code(Read & Write)

    • Project and Team (Read, Write & Manage)

Make sure to store your access token in a secure location - you will be asked to provide it during the SDLC setup process.

1. Creating SDLC Projects

An Instabase directory that houses an organized set of files and folders can be considered a project. The SDLC panel enables version management of that directory, with versions stored on a remote Git server. This means that a project can be created from scratch, or can be based on an existing Git repository.

Note that version pulling will overwrite any local changes that you have made on Instabase. In the case of an accidental overwrite, each SDLC operation creates a backup of your current folder at the same level of the current project with the name .backup-dir, where dir is the name of your directory.

Creating a Project from Scratch

To create a project when a remote repository does not exist, follow the activity below.

Activity

  1. Log in to Instabase.

  2. Navigate to the folder you want to manage using SDLC.

  3. Click the button in the upper-right corner that has three dots and looks like a graph (this is a Code Fork icon). If no SDLC management exists in this folder, you will see options for initializing the version management.

  4. Enter a name for your project under Project Name. This name can’t have spaces.

  5. Leave the Remote Path blank because these steps automatically create a remote repository for this directory.

  6. Enter the Branch Name of the branch you want to pull from and push to. The default branch name is master.

  7. Enter your access token for Access Token. This is the access token you generated in previous steps.

  8. Choose GitLab, GitHub, AzureDevops or BitBucket from the Remote Type drop-down menu, depending on where your access token was generated.

  9. (Optional) Change the host URL of that service. For instance, if you have an internal GitLab instance, enter the URL to that instance for Host.

  10. Click Create.

  11. Wait for the project creation to finish. After the project is created, your project name shows on a new panel. Select the project name to view the remote repository on your Git Provider.

Creating a Project from an Existing Repository

If there is an existing repository on Git that you want to manage in Instabase, follow the activity below.

Activity

  1. Log in to Instabase.

  2. Navigate to the folder you want to manage using SDLC.

  3. Click the button in the upper-right corner that has three dots and looks like a graph (this is a Code Fork icon). If no SDLC management currently exists in this folder, you will see options for initializing the version management.

  4. Enter the name for your project under Project Name. This name should match the repository name located on the remote Git Provider.

  5. Enter the remote path for your project. This should be the Git HTTPS url, such as https://gitlab.com/username/my-project.git.

  6. Enter the Branch Name of the branch you want to pull from and push to. The default branch name is master. If the specified branch does not exist for this repository, it is created for you.

  7. Enter an access token under Access Token, generated from following the prerequisites above.

  8. Choose GitLab, GitHub, AzureDevops, or BitBucket from the Remote Type drop down depending on where your access token was generated.

  9. (Optional) Change the host URL of that service. For instance, if you have an internal GitLab instance, enter the URL to that instance under Host

  10. Click Create

  11. Wait for the creation to finish. When completed, you should see a new panel listing your project name. Click the name to see the remote repository on the Git Provider. After refreshing, you can see your project folder with the files pulled from Git.

2. Pushing and Pulling New Project Versions

After an Instabase folder is setup with SDLC functionality, the remote repository is ready to receive new changes developed on Instabase.

Pushing a New Version

Versioning using is done by creating a commit on the specified branch in the connected Git repository. Follow the steps below to create a new version.

Activity

  1. Log in to Instabase.

  2. Navigate to a folder that is SDLC managed.

  3. Make a change to some file in your project.

  4. Click the button in the top right corner that has three dots and looks like a graph (this is a Code Fork icon).

  5. Click Push latest, enter a commit message using imperative language that describes the changes you made, and click Commit.

  6. The changes are pushed to the specified branch in the remote Git repository. After the version is pushed, click the Project name to see the updated remote Git repository. You should see a new commit with your changes.

Pulling a New Version

Pulling a version finds the version on the remote project, and copies it into your local Instabase directory. This pull overwrites any local changes that you have made on Instabase.

Activity

  1. Log in to Instabase

  2. Navigate to a folder that is SDLC managed.

  3. Click the button in the top right corner that has three dots and looks like a graph (this is a Code Fork icon).

  4. Click the arrow button next to the Pull latest button to display the version SHAs of the commits in your branch. The commits are listed in descending order of commit time. Click the version you want to pull.

  5. When the pull is done, the local directory will match the directory of that remote version.

3. Project Status

The icon and contents of the panel for an SDLC managed project indicate the current status of your local directory when compared to the top of your branch in the remote repository. Click the Refresh button next to the project name within the panel to see the most recent status. Possible statuses are:

  • Green Icon - Your directory is up to date with the remote.

  • Orange Icon - A new version of your directory is available on the remote repository.

  • Blue Icon - Your directory has local changes.

  • Red Icon - Your local changes have a conflict with the remote repository.

Conclusion

Great! Now you have seen how to use the SDLC process with Instabase.

You should now feel comfortable with how to:

  • Create a project with versions managed on GitHub, GitLab, Azure Devops or BitBucket Server

  • Pull and push versions for a project

  • View the current status of your local project compared against the latest remote version