GitHub Sync

Syncing iPaaS Solutions with GitHub

Use the Xurrent iPaaS GitHub App to manage iPaaS solutions in GitHub. It synchronizes and promotes changes across multiple iPaaS environments (for example: QA EU, QA US, Prod EU, Prod US) automatically whenever you push to a configured branch.

How it works

Each region and stage (QA, Production) has its own dedicated GitHub App. You install the required apps on your GitHub organization and grant them access to the repositories that contain your iPaaS solutions.

When you push changes to a branch that is linked to an iPaaS solution:

• GitHub sends a webhook to the corresponding iPaaS environment
• iPaaS imports the latest version of the solution
• If validation succeeds, the solution is automatically promoted
• If validation fails (for example, missing environment variables), the update is saved as a Draft, which you can complete in the iPaaS UI

A common setup is:

• main branch → staging/integration branch used for development
• qa branch → synced to all QA environments
• prod branch → synced to all Production environments

Prerequisites

Before you begin, ensure you have:

• Access to an iPaaS instance with permission to create and edit solutions
• Permission to create repositories in a GitHub organization
• GitHub organization admin access (required to install GitHub Apps at organization level)

For more details, see GitHub's documentation on Installing a GitHub App.

Step 1 — Create a solution in iPaaS

Create a new solution in your iPaaS instance as usual. This initial version will become the baseline for version control in GitHub.

Step 2 — Export the solution

From the solution page in iPaaS:

• Export the solution as a .zip file
• This file contains the full solution definition and configuration

Step 3 — Prepare your local repository

On your local machine:

1. Create a new folder for the solution
2. Unzip the exported file into this folder
3. Add a .gitignore file to exclude unnecessary system and temporary files from version control. You can use the recommended template provided in Appendix A — .gitignore template for iPaaS solutions.
4. (Optional) Add a README.md describing the solution and its environments

Your repository should contain:

• The extracted iPaaS solution files
• .gitignore file
• Optional: README.md

Appendix A — .gitignore template for iPaaS solutions:

# Editors / IDEs
.idea/
.vscode/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

Step 4 — Create a GitHub repository

Create a new repository in GitHub for the solution.

• Recommended: one repository per iPaaS solution
• Visibility: private, internal, or public (all are supported)

Step 5 — Push the initial code

From inside your local directory, initialize the repository and push the initial version to the staging (main) branch.

This initial commit establishes the base version of the solution and does not directly deploy to QA or Production environments.

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin <repository-url>
git push -u origin main

This creates the main branch as the staging branch, which will later be used to promote changes to qa and prod through pull requests.

Step 6 — Install the iPaaS GitHub App

Install the appropriate GitHub App for each environment (region + stage) you want to sync with. Each environment uses a dedicated app, so you manage access to each one independently.

QA apps use a green iPaaS logo so you can recognize them.

QA Table :

Production Table :

The apps are not yet listed on the GitHub Marketplace, so install them directly using the URLs above.

During installation, GitHub prompts you to choose which repositories the app can access. Select Only select repositories and grant access only to repositories that contain iPaaS solutions.

Only allowing the apps access to selected repositories:

• Cuts unnecessary webhook traffic
• Limits the app's access to relevant repositories
• Improves security and access control

You can modify the list of authorized repositories at any time from your GitHub settings.

Step 7 — Grant the app access to the repository

If you have already installed the iPaaS GitHub App and are adding a new solution repository:

1. Open your GitHub organization or personal account settings
2. Navigate to Installed GitHub Apps
3. Select the appropriate iPaaS GitHub App for each environment
4. Add the new repository to the app's Selected repositories list
5. Click on Install

Each environment-specific app that should synchronize the solution must have access to the repository.

For example, if a solution is deployed to:

• QA environments in all regions, and
• Production environments in all regions,

then all QA and Production GitHub Apps must be granted access to the repository.

Step 8 — Configure the solution in iPaaS

Repeat the following steps for each iPaaS environment (every region and stage combination) where the solution needs to be synchronized:

• Open the solution's Edit page in iPaaS
• Provide the following details:
  • GitHub repository
  • Branch name for the respective stage:
    • qa for QA environments
    • prod for Production environments
• Click Test GitHub Connection to verify:
  • The correct GitHub App is installed
  • The app has access to the specified repository
• Save the solution configuration

Note: The branch does not need to exist in GitHub at this point. It will be created and pushed in the next step.

Step 9 — Create and push the stage branch

Create and push the environment branches that match the branch names configured in iPaaS.

Example:

git checkout -b qa
git push -u origin qa

git checkout main
git checkout -b prod
git push -u origin prod

After pushing the branches, wait a few moments and refresh the solution edit page in iPaaS. Synchronization occurs asynchronously, so there may be a short delay before the update appears.

Once synchronization is complete, you should see:

• The latest commit SHA received from GitHub
• A status message indicating whether synchronization succeeded or failed

Step 10 — Make updates in iPaaS

Make changes to the solution in iPaaS using the Draft version.

Use Send shipment to validate the changes before exporting the solution.

Optional (if required):

• Extract blueprint
• Promote configuration
• Provision updates

Step 11 — Export the updated solution

Once validation is complete:

• Export the solution as a .zip file from iPaaS

Step 12 — Commit changes to GitHub

Unzip the exported solution into your local repository and commit the changes to the staging branch (main).

git add .
git commit -m "Update solution"
git push origin main

Step 13 — Promote to QA (via Pull Request)

In GitHub:

1. Create a Pull Request: main → qa
2. Request review and approval from a colleague
3. Merge the Pull Request

Merging triggers iPaaS synchronization to all QA environments.

Step 14 — Validate QA deployment

Verify in iPaaS QA environments:

• Solution is synced successfully
• Changes are promoted correctly
• Any provisioning is completed as expected

Step 15 — Promote to Production

After QA validation, in GitHub:

1. Create a Pull Request: qa → prod
2. Get approval from a reviewer
3. Merge the Pull Request

Merging triggers synchronization to all Production environments.

Step 16 — Validate Production deployment

Confirm in Production iPaaS environments:

• Sync completed successfully
• Solution promoted correctly
• Provisioning executed as expected

Why was my solution not promoted?

If validation fails, the imported version is saved as a Draft so you can complete any required configuration in the iPaaS UI.

Examples of validation issues include:

• Missing environment variable values
• Incomplete configuration settings
• Invalid references or mappings

Once you complete the required changes in iPaaS, you can promote the solution as usual.