Set Up the Project to Deploy to Production

By default, a project deploys extensions to the Development environment, which is the Oracle Cloud Application instance you were using when you clicked Edit Page in Visual Builder Studio. Follow these steps to deploy to the PROD instance, so users can deploy to it after their development and test cycles are complete.

The Oracle Cloud Applications PROD instance resides in a different identity domain from the DEV and TEST instances, which means you’ll need the URL for the PROD instance, as well as user credentials that VB Studio can use to deploy to this instance. These credentials must be those of a local user, not a federated identity, and must not require multi-factor authentication.

To set up a project to deploy to PROD:

1. Add the PROD instance to an environment
2. Create a production branch
3. Create and configure production build jobs
4. Configure the pipeline so that the packaging and deployment jobs run in succession
5. Run the production pipeline.

Add the Oracle Cloud Application's Production Instance to an Environment

Only one Oracle Cloud Applications instance can be added to an environment. As the Development environment already points to the TEST instance (or DEV, if you asked Oracle to re-associate it), you must create a new environment for the PROD instance.

To create a new environment for the PROD instance:

1. In the VB Studio navigator, click Environments.
2. Click + Create Environment.
3. In the Service Instances tab, click + Add Instance.
4. In the Add Service Instances dialog box, select the Oracle Cloud Applications option button.
5. Under Authentication Method, select the Application Credentials option.
6. In Base URL, enter the Oracle Cloud Application's base URL.
7. In Instance Name, if required, update the instance's display name. The name will be displayed in the Service Instances tab.

8. In Username and Password, enter the credentials of a user who can access this Oracle Cloud Applications instance.

   These credentials must be those of a local user, not a federated identity, and must not require multi-factor authentication.

9. Click Add.

If the newly added instance stays in the Unknown status for some time, it usually indicates that the IDCS Application provisioning may have failed. VB Studio added the Oracle Cloud Applications instance, but can't access it. In this case, click Actions and select Remove to remove the Oracle Cloud Applications instance from the environment, and then click Add to add it again.

Create a Production Branch

Follow your organization's guidelines to create a branch and protect it from unverified changes. To protect the branch, you can set merge restrictions, make the branch private, and restrict who can push commits to it, or freeze it.

1. In the left navigator, click Git .
2. Click the Refs view and then click Branches .
3. From the Repositories drop-down list, select the repository.
4. Click + Create Branch.
5. In the New Branch dialog box, in Name, enter the branch name. From the Base drop-down list, select the main branch as the base branch.
6. Click Create.

After creating the production branch, any changes pushed to the main branch aren't automatically available in the production branch. You must create a merge request or manually push the changes to the production branch.

If you want to set merge restrictions on the production branch, see Set Review and Merge Restrictions on a Repository Branch. To freeze the branch or make it private, or set other restrictions, see Protect a Branch.

Create and Configure Production Build Jobs

You need to set up some packaging and deployment jobs before you can deploy extensions to your Oracle Cloud Application's PROD instance. Follow this process:

1. Migrate the configurations to the production Oracle Cloud Application instance. See Overview of Configuration Life Cycle and Migration in Configuring and Extending Applications for instructions.
2. Create a build job that packages the extension. See Create the Production Packaging Build Job for instructions.
3. Create a build job that deploys the extension to the production instance. See Create the Production Deployment Build Job for instructions.
4. (Optional) Restrict who can see or edit the production build jobs or run their builds. See Configure a Job's Privacy Setting for instructions.
5. Configure the pipelines to run the packaging and deployment jobs in succession. See Create and Configure the Production Pipeline for instructions.
6. Run the production pipeline to package the extension and deploy it to the production instance. See Run Production Pipelines for instructions.

Before You Configure Build Jobs and Pipelines

Here are some things you need to know before you configure and run build jobs and pipelines:

• Make sure that the source and target instances are of the same release, with the same standard and one-off patches applied to both environments.
• In the development packaging job, if you changed the default artifact's file name, get the new name and its path.
• If you configured the development packaging job to overwrite the application's version defined in visual-application.json, get the new version. You'll configure the production's packaging job to use the same version.

Create the Production Packaging Build Job

The packaging job generates an extension artifact that's ready to deploy to the mainline.

1. In the left navigator, click Builds .
2. In the Jobs tab, click + Create Job.
3. In the New Job dialog box, in Name, enter a unique name.
4. In Description, enter the job's description.
5. In Template, select the System Default OL7 for Visual Builder template.
6. Click Create.
7. Click Configure .
8. Click the Git tab.
9. From the Add Git list, select Git.
10. In Repository, select the Git repository. In Branch or Tag, select the production branch.
11. Click the Steps tab.
12. From Add Step, select Application Extension, and then select Package.
13. By default, the packaging step minifies the application's source code before running the build. If you don't want to minify the source files, deselect the Optimize extension check box.

    Minification is a process to remove the unnecessary characters (such as blank spaces, new lines, and comments) from the source code and reduce the size of the files, making the transfer of files consume less bandwidth and storage.

    Note:

    When you deselect the Optimize extension check box, this warning is displayed: Optimization not selected. Packaging without optimization can cause performance problems, so avoid doing so unless you're debugging or troubleshooting.
14. (Optional) If you want to change the artifact file's name, in Artifact, enter the new name. By default, it is extension.vx.
15. (Optional) If you configured the development packaging job to overwrite the extension's default version defined in the visual-application.json file, specify the same version in Extension Version.
16. Click the After Build tab in the Job Configuration window.
17. From Add After Build Action, select Artifact Archiver.
18. In Files to archive, enter the build artifact name.

    You can use wild characters. For example, *.vx. Make sure that you include the path for the Application Extension build artifact.

    If you entered a value in the Target Directory field in Copy Artifacts for the deployment job, it is considered to be a subdirectory of the workspace and should be part of the artifact's path in the Build Artifact field.

19. If you want to discard the build's old artifacts, click Settings . In the General tab, select the Discard Old Builds check box and specify the discard options.
20. Click Save.

Create the Production Deployment Build Job

The deployment job deploys the extension's artifact that was generated in the packaging job to the Oracle Cloud Application's production instance. Before you create the job, make sure you have credentials that VB Studio can use to access the Oracle Cloud Application's PROD instance.

1. In the left navigator, click Builds .
2. In the Jobs tab, click + Create Job.
3. In the New Job dialog box, in Name, enter a unique name.
4. In Description, enter the job's description.
5. In Template, select the System Default OL7 for Visual Builder template.
6. Click Create.
7. Click Configure .
8. Click the Before Build tab.
9. From Add Before Build Action, select Copy Artifacts.
10. In From Job, select the packaging job that generated the extension's artifact.
11. In Which Build, select one of the following:
    • Last successful build (default)
    • Last keep forever build
    • Upstream build in this pipeline instance
    • Specified by permalink
    • Specific build
    • Specified by build parameter

    Depending on what you select, you may be prompted to select which permalink, build, or build parameter you want to be used.
12. Leave other fields with their default or empty values.
13. Click the Steps tab.
14. From Add Step, select Oracle Deployment.
15. In Target Instance, select the environment with the Oracle Cloud Application's production instance.
16. In Username and Password, enter the credentials of an IDCS user who is not only an Oracle Cloud Applications user, but one who can connect and deploy to the Oracle Cloud Application 's production instance.
    These credentials must be those of a local user, not a federated identity, and must not require multi-factor authentication.
17. If you changed the archive artifact files default file names in the production packaging job, in File names, select Use custom file names.

    In Sources and Build Artifact, enter the same file names (with the path) that you specified in the packaging job.

18. Click Save.

Note:

If you develop an extension on, say, 23D in your Test environment, then want to deploy the extension to your 23C Prod environment, you'll have to wait until your Prod instance has been upgraded to 23D before you can deploy successfully. In most cases, there shouldn't be more than a two week gap between pod upgrades.

Configure a Job's Privacy Setting

The project owner can mark a job as private to restrict who can see or edit a job's configuration, or run its build:

1. In the left navigator, click Project Administration .
2. Click Builds.
3. Click the Job Protection tab.
4. From the jobs list, select the job.
5. Select the Private option.
6. Select the Allow commits and triggers to start this private job checkbox if you want SCM commits and triggers to be able to automatically run this job.
   
   

   
   Description of the illustration job-protection-all-commits-and-triggers-checkbox-selected.png

   
   

   With the checkbox selected, periodic triggers will run any job or pipeline, including private jobs set to allow commits and triggers to start the private job. If a private job with this option selected is included in a pipeline and a non-authorized user attempts to run the pipeline manually, the private job won't run but periodic triggers and SCM commits will.

   Leave the checkbox unselected if you don't want the job to be started when it is triggered by an SCM commit or timer.

   Note:

   Best Practice:

   If you use the checkbox to enable the protected build to be triggered by an SCM commit, you need to protect the branch that the build job is tied to. If you don't do this, anyone can trigger the protected build by making a commit to trigger the build.

7. Click in the Authorized Users/Groups field to view a list of Users and Groups that have permission to access this project.

   From the list, select one or multiple users and groups. Don't forget to add yourself.

   
   

   
   Description of the illustration job-protection.png

   
   
8. Click Save.

You can see if a job is private from several places in the VB Studio user interface. A private job is indicated by a Lock icon:

• In the jobs list found on the Project Administration tile's Builds page's Job Protection tab, to the right of each protected job's name.

• In the Private column on the Builds page's Jobs tab.

• In the jobs shown in the the Builds page's Pipelines tab.

An unauthorized user can't run a private build job manually, or through a pipeline, or via an SCM/periodic trigger.

Create and Configure the Production Pipeline

To ensure the deployment job runs automatically after the packaging job, create a pipeline and set the dependency.

1. In the left navigator, click Builds .
2. Click the Pipelines tab.
3. Click + Create Pipeline.
4. In the Create Pipeline dialog box, in Name and Description, enter a unique name and description.
5. Click Create.
6. On the Pipeline Configuration page, right-click the Start node and select Add New Start jobs.
7. Click in the Select new on success job(s) field, select the packaging job and click Save.
8. Right-click the packaging job and select Add, then Add New On Success Jobs.
9. Click in the Select new on success job(s) field, select the deployment job, and click Save.

   Here's an example of the final pipeline:

   
   

   
   Description of the illustration build_appextn_prod_pipeline_deploy.png

   
   
10. Click Save.

Run Production Pipelines

Before you run production build jobs or a production pipeline, make sure that all code changes have been pushed to the production branch and there are no open merge requests.

1. In the left navigator, click Builds .
2. Click the Pipelines tab.
3. In the production pipeline's row, click the Actions menu and select Run Pipeline.

After a successful build, you can see the deployed application's link in the Environments page's Deployments tab. You should also notify the Oracle Cloud Applications administrator that the extension has been pushed to the Oracle Cloud Application's production instance.