Git Quick Setup Guide

Connect a Koodisi application to Git in single mode (one app per repository) or multi mode (several apps in one repository). Do the three checks below first: most failed setups skip one of them.

Download this guide as a PDF to share with your team.

Before you start

1. Get the repository URL. In your Git provider (Azure DevOps, GitHub, GitLab), copy the repository's HTTPS clone URL, for example https://dev.azure.com/org/project/_git/my-repo.
2. Create a Personal Access Token (PAT). It needs read and write access to code for that repository.
3. Check the app type. The app must be an Orchestration app. Bundle apps can't use Git.

Which mode to pick

Use single mode unless your apps are released together. You choose the mode when you connect the app.

	Single mode	Multi mode
Apps per repository	One	Several, each in its own folder
Branches	Belong to that one app	Shared by every app in the repository
Deleting an app	Removes it from your workspace only	Can also remove files that other apps share
Pick it when	Apps release independently	Apps release together, or share components

For more on the trade-offs, see Single vs. Multi-Module Repositories.

Option A: single mode, new app

1. In the Applications panel, select + > Create.
2. Choose New Application.
3. Enter a Name. Leave Application Type as Orchestration.
4. Turn on Enable Git control.
5. Paste the repository URL into Remote Url.
6. Leave Multi module repository unticked.
7. Choose how to give your credentials:
   • New Credentials: enter a credential name, choose the Git Provider, then your username and Personal Access Token. Use this the first time.
   • Use Existing Credentials: pick one you saved before.
   • Continue Without Credential: Koodisi asks for them on every Git action.
8. Select Create.
9. Do the first commit. The app isn't in the repository until you do.

Option B: multi mode, several apps in one repository

The first app you connect sets the shared repository for the whole workspace. Every app after it reuses that URL.

First app

1. Follow Option A, steps 1 to 5.
2. Tick Multi module repository.
3. Choose your credentials and select Create.
4. Do the first commit.

Every app after that

1. Select + > Create > New Application, enter a Name, and turn on Enable Git control.
2. Tick Multi module repository. Remote Url fills in from the workspace. Leave it as it is.
3. Choose your credentials and select Create.
4. Do the first commit.

Don't change the pre-filled URL. Koodisi warns "This action will move all your data from the current repository to this repository."

All apps in the repository share branches, so a branch made for one app exists for all of them.

Option C: add Git to an app you already built

1. In the Applications panel, right-click the app.
2. Select Add Git to Application.
3. Paste the repository URL into Remote Url.
4. Tick Multi module repository only if the repository holds several apps.
5. Choose your credentials and select Save.
6. Do the first commit. Connecting the app doesn't push anything.

First commit

After Options A, B or C your app is connected, but its files aren't in the repository yet. The first commit pushes them and creates the branch.

1. Select the app, then select the Version Control icon in the right sidebar.
2. On the Changes tab, select Stage all changes.
3. Select Commit and Push.
4. Keep or edit the commit message, then confirm.

It worked when Koodisi shows "All changes are committed and pushed successfully." The files then appear in your Git provider.

Teammates: clone the app

Teammates clone the app from Git. They don't create it again.

1. Select + > Create > Clone from git.
2. Enter a Name. In multi mode, it must match the app's folder name in the repository exactly.
3. Paste the repository URL into Remote Url.
4. Tick Multi module repository if the repository is multi mode.
5. Enter your own credentials, then select Create.

Deployment profiles aren't stored in Git, so each person who clones has to recreate them.

Common errors and fixes

You see	What it means	Fix
The saved Git credential may be invalid or expired	The PAT is expired or wrong	Create a new PAT and update the credential
The credential does not have permission for this repository or operation	The PAT lacks access	Give the PAT read and write code access to the repository
Verify the repository URL and the credential's repository access	Wrong URL, or the PAT can't see the repository	Copy the HTTPS URL again, then check the PAT's access
Pushes to this branch are not permitted; you must use a pull request	The branch is protected	Push to a feature branch, then raise a pull request
Bundle applications can't be used with Git	The app is a Bundle app	Use an Orchestration app
Enable Git control is missing	Git isn't turned on for the workspace	Ask your admin to check the workspace Git settings

For every Git error message, see the Troubleshooting Guide.

Related docs

Stage	Doc	Use it for
Understand	The Development Lifecycle	The path from first build to production
Understand	What are Git-enabled applications?	What Git adds to an app
Understand	Single vs. Multi-Module Repositories	Choosing a mode
Set up	Creating a Git-Enabled Application	Options A and B in full
Set up	Add Git to an Existing Application	Option C in full
Set up	Managing Credentials	Saving and updating Git credentials
Set up	Git Branching Policy	Branch naming rules for the organization
Set up	Protecting Deployment Branches	Locking the branches you deploy from
Daily work	Using Git with Applications	Commit, push, pull and branches
Daily work	Reviewing Commit History	Seeing who changed what
Daily work	Git Workflow for Development	Organizing branches
Daily work	Merging and Pull Requests	Getting work into the main branch
Daily work	Schema Guidelines	Keeping schemas Git-friendly
Daily work	Working with Git Applications: Best Practices	Habits that avoid trouble
Team	Cloning Git Applications	Teammates getting a copy
Team	Parallel Development with Multiple Developers	Several people on one app
Team	Managing Deployment Profiles	Recreating profiles after a clone
Fix problems	Troubleshooting Guide	Every Git error message
Fix problems	Handling Merge Conflicts in NX	Recovering from a conflict
Fix problems	Managing the Local Datastore	Clearing and re-cloning local data
Clean up	Deleting Git Applications	Remove vs Delete, by mode