Deploy a Visual Application Through CI/CD Pipelines

Deploying a visual application requires you to commit and push the changes in your workspace to a Git repository branch. Your changes are then packaged and deployed to your environment's Visual Builder instance, either directly or via continuous integration and delivery (CI/CD) pipelines. Follow these steps when your visual application's CI/CD pipeline setting is enabled for the remote branch you're merging to.

Note:

Visual applications are, by default, deployed using the CI/CD pipeline enabled for your project's main branch. If you don’t want to use a CI/CD pipeline for deployment, change the CI/CD pipeline setting in the Settings editor. See Enable or Disable the CI/CD Pipeline for Deployments.

To deploy a visual application, you can use the Publish option in the header. The Publish option merges the content of your working branch to the target branch selected in the Publish dialog.

During the early stages of development, you might prefer to keep your work separate from your project's main branch. You can do this by merging your visual application to a different branch. When you’re ready to test your changes, you might also want to deploy your changes to a test instance of Visual Builder. To set this up, you'll need to create the new branch, new packaging and deployment jobs, and a pipeline to deploy your changes to a Visual Builder test instance.

When you’ve tested your visual application and are ready to make your changes public, you can merge to main or maybe to a production branch that you've created. Keep in mind that you'll need a production instance of Visual Builder to deploy your changes to production.

You can exercise control over when branch commits actually trigger a build pipeline. Maybe you don't want to deploy your visual application every time a team member pushes changes to a feature branch. Instead, you'd rather run the pipeline manually once a week. You can do this by configuring the packaging job, and then running the pipeline manually as needed.

Note:

To deploy your visual application, the pipeline's deployment job must be configured to deploy to the Visual Builder instance.
  • If the deployment job is set up for OAuth (recommended), authorization must be provided for OAuth tokens to be created with the credentials of a user who has permissions to connect and deploy to the Visual Builder instance. You won't be able to publish without this authorization. It is recommended that you authorize your connection during initial job configuration—though you'll be prompted to authorize missing or expired OAuth tokens when you click Publish.
  • If the deployment job uses Basic authentication, credentials of a user who can connect and deploy to the Visual Builder instance must be provided. If your project owner hasn't provided these credentials, you'll be prompted to provide them when you click Publish the first time. If your credentials don't allow you to deploy to the Visual Builder instance, talk to your project owner or an administrator to get credentials that you can use. Your administrator can choose to enter the credentials directly in the build job, so you aren't prompted for them when you try to deploy your app.

See Configure the Deployment Job in Administering Visual Builder Studio for details.

When you're ready to deploy your changes:
  1. Click Publish in the header.

    Note:

    If the Publish option is not enabled, you're likely using a scratch repository instead of a real Git repo. If that's the case, and you do want to deploy your work, create a new repo, as described in Push a Scratch Repository to a Remote Repository.
  2. If changes exist, enter a comment in the Commit Message area to describe your changes. A commit groups the changed files and provides a description to identify the group.
  3. In the Target Branch field, select the branch in the remote repo to merge to.

    The first branch in this list is always the repository's default branch, main, conveniently followed by the last 10 branches you created merge requests for (if any). Any remaining branches follow in alphabetical order. This flexibility lets you more easily deploy and test your new feature development work, if you're not yet ready to merge those changes into your repository's main branch.

  4. If you land on the Merge Now tab, it means you have permission to push your changes directly to the selected target branch without getting it approved by other project team members.

    The New Working Branch Name field displays with an automatically populated new name for your working branch. You can accept the default, but it's recommended to change to a name that's more meaningful.

    Once you deploy a branch, you can no longer use it (or your local copy of it). Instead, VB Studio automatically creates a new working branch using the value in this field, and switches your workspace to it for any future changes.

  5. As a best practice, you can request someone to review your changes by creating a Merge Request. Switch to the Merge After Review tab, enter a comment summarizing your changes, add at least one reviewer, and specify the issue you were working on. Optionally, enter a description of all your changes (not just this commit) in the Merge Request Description field, using the convention established for the template (Markdown, Confluence, or Textile). If you need help, use the link to the associated reference.
    Description of vbs-publish-dialog2.png follows
    Description of the illustration vbs-publish-dialog2.png

    Note that the New Working Branch Name field doesn't display because, if a merge request is created, VB Studio won't automatically create a new working branch and switch your workspace to it. After the merge request is approved and your visual application is deployed, however, you should manually switch the workspace to a new working branch.

    If you see only the option to commit and merge your changes via a merge request (that is, there's no Merge Now tab), that means the project owner or an administrator has set things up so that all changes must always be reviewed and approved via a merge request before they are merged to the target branch. In this case, summarize your changes in the Publish dialog, add at least one reviewer (if no one is specified), and specify the related issue in order to create a merge request. (Once the request is created, you can look for it on the Merge Requests page. For details on how to work with merge requests, see Review Source Code with Merge Requests in Using Visual Builder Studio.)

    If a merge request is required but a CI/CD pipeline hasn't yet been set up, the dialog will display a message indicating that the Publish action will only merge your changes; to fully deploy your visual application, you'll need to first set up a pipeline for the remote branch.

  6. Click Publish.

    Tip:

    Use the details in the Publish dialog to take note of the environment that your changes will be deployed to, which is typically the deployment target specified in the pipeline that's enabled for the target branch.
  7. If the deployment job in your CI/CD pipeline is missing the credentials required to connect and deploy to your environment's Visual Builder instance, you'll be prompted to complete some additional steps:
    • If you see a message that authorization is required, it means the deployment job is set up for OAuth and requires authentication for the OAuth connection to the target instance:
      1. Click OK.

      2. If prompted, enter the credentials of a user who can access the target Visual Builder instance.

        If you land on the Authorize Jobs page, your Deployment job may have missing or expired OAuth tokens. Click Authorize, enter the credentials of a user who can access the target instance, and click Authorize.

      3. Once authorization is complete, click Publish again in your workspace's Publish dialog.
    • If you see a message about missing deployment credentials, it means the deployment job uses Basic authentication and requires the credentials of a user who has permissions to access the target instance. Enter valid credentials and click Add Credentials and Continue.

After VB Studio performs the Git actions necessary (commit, fetch, merge, push) to merge the changes in your local repository to the specified target branch (in this case, main, as shown here), it starts the pipeline to package and deploy the changes to your Visual Builder instance:
Description of vbs-publish-git-actions-complete.png follows
Description of the illustration vbs-publish-git-actions-complete.png

You should now see notifications in the bottom right corner of your workspace, indicating that your application's package and deploy jobs have started. (If you miss these notifications or want to track progress of each job, look for them under Notifications in the header.) If a build job fails, you'll see something similar to this message and will need to resolve the issue (click Open job to view the job's details and take action):
Description of build-notifications.png follows
Description of the illustration build-notifications.png

After the deployment job has successfully completed, you can view your changes deployed to the Visual Builder instance in your environment. See View Deployed Visual Applications.