1. Using Visual Builder Studio
  2. Common Tasks
  3. Build Your Applications
  4. Run Jobs in a Pipeline
  5. Add Manual Pipeline Approvals

Add Manual Pipeline Approvals

You can set up and use a manual approval process to pause a pipeline run, so one or more authorized users can approve executing the rest of its run. This is done in the Pipeline Designer by adding an approval item to the pipeline where you want the pipeline execution to stop so someone with the necessary permissions can approve or reject executing the rest of the pipeline. The pipeline run pauses, while it waits for approvals. Once the approvers approve, the pipeline run resumes building. If the approvers reject, the pipeline run stops and returns a failed status. The project's activity stream displays pipeline approval-related activities when a pipeline pauses for approval, an approver approves or rejects a pipeline, and when the pipeline resumes after approval.

Manual approval functionality involves four main tasks:

Create a Pipeline Approvers Group for Your Project

The pipeline approvers group lets you approve all manual approval pipelines that are not restricted by specific groups.

An approver is always part of a group. A group of approvers can approve certain pipelines only. Certain pipelines can be approved by certain groups of approvers only.

The approvers in the "Default Approver Group" can approve or reject any Manual Approval pipeline. The default pipeline approvers group is made up of individuals (approvers) who can approve any unrestricted pipeline (a pipeline that doesn't require approval from a specific group). So, you can add approvers to the default group but you can't limit that approval group to any specific pipeline.

To do that, you need to create a group to approve specific pipelines. This group allows you to add both approvers and pipelines. Then later, when you add the Manual Approval item in the pipeline designer, you can designate approvers as required approvers and specify the minimum number of approvers needed to approve the pipeline. See Add a Manual Approval Item to Your Pipeline at Design Time.

To add pipeline approvers to your project:
  1. In the left navigator, click Project Administration Project Administration icon.
  2. Go to the Pipeline Approvers tab.


    Description of create-approval-adding-group.png follows
    Description of the illustration create-approval-adding-group.png

    Notice that a Default Approver Group has already been set up for the project. This group has no members initially. Its approvers can approve any pipelines that isn't restricted by a specific approval group. If the default group has no approvers, however, nobody will be allowed to add any approvers to any pipelines in the project. Note that pipelines can't be added to this group.

    Add the default pipeline approvers now:

    1. Select the default group.
      The Configure Pipeline Approvers dialog displays.
    2. In the Configure Pipeline Approvers dialog, click in the Approvers field and select one or more approvers from the list and add them as default approvers.
    3. Click Save.

      Now, for any pipeline you create in the Pipeline Designer going forward in the project, you'll see and be able to select from the list of default approvers you added here.

    Tip:

    Using this approach only isn't an ideal solution for most organizations. A better approach would be to also create an approval group for a specific pipeline (or multiple pipelines). Once you do that, the default group no longer applies to that pipeline (or pipelines). Proceed to the next step and begin this process.

  3. Click + Create Pipeline Approvers.
    The Create Pipeline Approvers dialog displays.


    Description of create-approval-form-blank.png follows
    Description of the illustration create-approval-form-blank.png

  4. Enter a name for your group in the Name field (required) and optionally describe the group in the Description field.
  5. Click in the Approvers (Required) area and select the project members you want to add as approvers. You can also add individual members from a local group, which are listed along the left panel. (Local groups are created at the Organizational level and added to the current project.) To add a team member from a local group, click the Approvers dropdown and select the member you want to add.

    This step is required. Approvers you add to this approvers group will also appear in the list of approvers that you can select in the Pipeline Designer, when you configure the Manual Approval item (node). See Add a Manual Approval Item to Your Pipeline at Design Time.

    Note:

    Users in Oracle Cloud Application environments that have multiple VB Studio instances in different identity stripes have username strings that include the environment name, where that user has been defined. Since a unique user may have been defined for multiple environments, this format ensures that one identity can be distinguished from that user's other unique identities. This should help you select the correct user to add.
  6. Click in the Pipelines area and optionally add the pipeline(s) that will require pipeline approvals.
  7. Click Create.
    You can see the group you just added, on the left, under the Default Pipeline Approvers group.


    Description of create-approval-completed.png follows
    Description of the illustration create-approval-completed.png

When you no longer need the group, click Delete Delete icon. You'll be prompted to verify that you do want to remove your pipeline approvers group.


Description of create-approval-delete-group.png follows
Description of the illustration create-approval-delete-group.png

Click the Delete button and remove the group. Otherwise, click Cancel.

Add a Manual Approval Item to Your Pipeline at Design Time

As you're creating your pipeline in the Pipeline Designer, you can add a pipeline approval. You do this by right-clicking on an upstream Job node and selecting the Add Manual Approval context menu item. When the node is added to the pipeline layout, its appearance is quite different from that of a Job node, so it's easy to differentiate between them.

Like a Job item, a Manual Approval item can be used with the fork-join layout pattern. That is, it can be a downstream item of a single upstream Job or a join of multiple upstream Jobs. Once it has been approved, it can trigger a single downstream job or fork multiple downstream jobs. However, although you can join multiple upstream jobs to and fork multiple downstream jobs from an Approval item, you can't use the Approval item itself as one of the joining items.

Note:

If you haven't defined any default approvers yet, you won't be able to use the manual approval functionality with any pipelines, because you can't add any approvers for that pipeline. The default approval group applies to any pipeline. Before you try to add approvals to a pipeline, you must add approvers to the default approvers group so you have a pool of approvers from which you can select when you define approvers for a pipeline in the Pipeline Designer or when you create an approval group and associate it with a specific pipeline (or pipelines).

See Create a Pipeline Approvers Group for Your Project.

After you add a Manual Approval node to your pipeline layout, you'll be presented with a dialog to configure approvers for your pipeline. If you don't want to configure them now, you can right-click on the approval item later and select the Configure context menu item, which displays the dialog you use to configure approvers.)

You can use the Configure dialog to:
  • Add or remove one or more approvers (only those who can approve this pipeline).
  • View information about the group of approvers, making it easier for you to determine if you're picking up the correct approver.
  • If you've selected multiple approvers, you can mark All or n number of approvers to enable approval for the approval item.
  • Mark one or more approvers as required. Required approvers must approve; all other approvers are optional.

    That is, if three approvers (approver1, approver2, approver3) are selected and approver2 is marked as required, if at least 2 approvers must approve, then one of those two approvers must be approver2.

If you already configured approvers, when you hover over the Manual Approval node, you can view information about it. If you haven't configured any approvers for the pipeline, the warning marker next to the node indicates that you need to configure approvers. The tooltip you see when you mouse over it provides information that explains how to configure the required approvers.

Let's step through this process using an example. We could start with a very simple pipeline that has two jobs and an approval but it may be more interesting and realistic to create one that has joins and forks. If you already have a pipeline with two jobs, each connected to the Start node, you can skip to step 8 and start there. Otherwise, start at the beginning.
  1. In the left navigator, click Builds Builds.
  2. Click the Pipelines tab.
  3. Click + Create Pipeline.
    The Create Pipeline dialog is displayed.
  4. In Name and Description, enter a unique name and a description, respectively, then optionally select the appropriate check boxes for autostarting the pipeline and disable manual or automatic builds of the jobs that are part of the pipeline when the pipeline is running.
  5. Click Create.
    The pipeline configuration page opens immediately after you create the pipeline.
  6. To add a new start job, right-click the Start node, and select Add New Start Jobs.
  7. Search for and select the jobs that you want to add, then click Save.
  8. Right click the first job (Job 1) and select Manual Approval, then select Add New Approval.
    Pipeline Designer window with gray Start node connecting to Job 1 and to Job 3, both shaded blue. After right-clicking on Job 1, the context menu shows Manual Approval and then Add New Approval being selected.
  9. Right-click the second job (Job 3) and select Manual Approval, then select Connect to Existing Approval.
    Pipeline Designer window with gray Start node connecting to Job 1 and to Job 3, both shaded blue. Job one also connects to an Orange Approval node. After right-clicking on Job 3, the context menu shows Manual Approval and then Connect to Existing Approval being selected.

    The Connect to Existing Approval dialog opens.

  10. Click the Select Approval field and, from the dropdown list, select the approval to invoke when this job completes (Approval, in this example), then click Save to close the dialog.
    Pipeline Designer window with gray Start node connecting to Job 1 and to Job 3, both shaded blue. Both jobs connect to an orange Approval item.

    The approval will wait for both jobs to finish before notifying any approvers you configure.

  11. Right click the approval item, select Edit Approval.
  12. In the Approvers section, click the Add Approvers field and use the selector to choose the approvers that can approve this manual approval from the list displayed.

    Here we've selected Alex Admin and Clara Coder.


    Description of add-approvers-alex-clara.png follows
    Description of the illustration add-approvers-alex-clara.png

    Note:

    Users in Oracle Cloud Application environments that have multiple VB Studio instances in different identity stripes have username strings that include the environment name, where that user has been defined. Since a unique user may have been defined for multiple environments, this format ensures that one identity can be distinguished from that user's other unique identities. This should help you select the correct user to add.
  13. Toggle the Required setting to on to make the approver's approval mandatory.
  14. Repeat for all the project members you want to be approvers.
    If you select more than one approver from the list, you'll see a field for setting the Minimum number of approvers before the pipeline can proceed field filled in with one approver, who is required.

    The minimum number must always be equal to or greater than the total number of required approvers. For example, if Alex Admin and Clara Coder are both selected as required reviewers, then the minimum number of approvers must be at least two. If you wanted either Alex Admin or Clara Coder's approval to allow the pipeline to continue, then you would set both of them to not required and set the number of approvers to 1.

  15. In the Expiration Duration section, click the Set duration before expiration check box.
  16. Use the Days, Hours, and Minutes selectors or enter values to set the length of time to wait for an approval.
    If you enter or select a value of 72 in the Hours field, for example, it will be converted to a value of 3 in the Days field. Similarly, 25 hours will be converted to 1 day and 1 hour.
  17. Click Save to exit the values you set.
  18. Right-click the approval item again and select the Add New On Approval Jobs option.
    The Add New On Approval Jobs dialog displays.
  19. Select a new on approval job, or select multiple jobs.
    We're adding two jobs, Job 2 and Job 4.

    Add New On Approval Jobs dialog showing Job 2 and Job4 being added in the Select new on approval jobs field. The Cancel and Add buttons are at the bottom of the dialog. The Add button is active.

  20. Click Add to add the two jobs to the pipeline.
    Pipeline designer showing the completed pipeline with an approval. From the gray Start node, the pipeline runs blue shaded Job 1, then blue shaded Job the before arriving at the Orange Approval item. After being approved to resume the pipeline run, blue shaded Job 2 and blue shaded Job 4 will be executed.
  21. Click Save to save the pipeline.
    The Pipeline Details screen is displayed.

    Pipeline Detail screen for myPipeline, showing the Pipeline Run History (no pipeline runs found) and the Pipeline Run Trend (No data available). This is expected, since this precedes the initial pipeline run. The View Layout, Configure, and Delete buttons are inactive. The Run button is active and was just selected. To its right is the Auto Refresh toggle, which has been selected. The Run Log icon is below the toggle, but can't be selected because the pipeline hasn't been run yet.

  22. Click Run to run the pipeline.
    If you don't see a notification, go to the Profile tab your user account and, under User Preferences, check that the user has been verified. See Add Manual Pipeline Approvals.
There are a few restrictions for manual approvals. You may encounter these when you are prevented from saving a newly created pipeline or one that's been modified:
  • You can't create an approval item from the Start node. You can only create it from a job (or jobs) downstream from the Start node.
  • You can't configure parallel approvals. If you try, when you attempt to save the configuration, you'll see the message, "Only one manual approval can be in effect at any given point in time. Your pipeline has multiple paths which can result in more than one approval to be active at the same time." Click OK to dismiss.
  • You can't have random jobs in the pipeline that aren't connected to start or to approvals or to other downstream jobs. "Pipelines with manual approval cannot have unconnected jobs or approvals. The following jobs or approvals are not connected to start: Job1".
  • You can't introduce jobs that bypass the approval(s).

Note:

Currently, you can't resume a pipeline after it has been rejected. You need to address and correct the issue(s) that caused an approver to reject completing the pipeline run and then restart the pipeline and approval process.

Approve the Manual Approval when the Pipeline Runs

If you're an approver, you can either approve or reject a Manual Approval action from the Pipeline Run page, where the graph or layout for the pipeline run is displayed. You can also add comments about why you approved or rejected the approval.

  1. In the graph, locate the yellow Approval item.

    Description of manual-approval-wait.png follows
    Description of the illustration manual-approval-wait.png

    The approval node is yellow, which indicates that some action is needed. The spinner indicates that the approval process is ongoing and likely in a waiting state.
  2. Hover over the approval node.
    You'll see that the pipeline is waiting for approval, how many approvals are needed, how many approvals have been approved, who the approvers are, how many approvals are pending, the length of time before the approval expires (and will be automatically rejected), and so on.


    Description of manual-approval-mouseover.png follows
    Description of the illustration manual-approval-mouseover.png

  3. Right click the approval item and select Approve/Reject Details.


    Description of manual-approval-approve-reject-details.png follows
    Description of the illustration manual-approval-approve-reject-details.png

    The Approval Details dialog is displayed.
    Description of manual-approval-approval-details-dialog.png follows
    Description of the illustration manual-approval-approval-details-dialog.png

    Note:

    Users in Oracle Cloud Application environments that have multiple VB Studio instances in different identity stripes have username strings that include the environment name, where that user has been defined. Since a unique user may have been defined for multiple environments, this format ensures that one identity can be distinguished from that user's other unique identities. This should help you select the correct user to add.
  4. Two approvals are needed. It looks like alex.admin-dev already approved, so now alex.admin-test (the blue stripe indicates that that's you) needs to approve or reject the run.

    Select one of the options:

    • Select Approve.

      A confirmation message shows that an approval has been submitted. The pipeline will continue executing. After the approval has been completed, the approval item will turn green, and any downstream jobs will too after they successfully execute.
      Description of manual-approval-approved.png follows
      Description of the illustration manual-approval-approved.png

      If you check the status, you'll see a green check Approved icon, indicating that the pipeline run was successful.

    • Select Reject.

      You'll be prompted to confirm that you want to reject the approval and will be allowed to add a comment explaining why you chose this action.
      Description of confirm-rejection.png follows
      Description of the illustration confirm-rejection.png

      The approval item turns red and the pipeline execution halts. No downstream jobs are executed so they remain white, instead of completing and turning green. When you mouse over the approval node, you'll see that it was rejected and the comment that was added in the confirmation window.
      Description of manual-approval-rejected.png follows
      Description of the illustration manual-approval-rejected.png

      The red thumbs down icon Rejected icon, at the top of the screen, indicates that the pipeline run was rejected.

      Tip:

      If you mouse over the rejected icon in the Status column of the Approval Details screen, this is representative of what you may see.
      Description of mouseover-reject-status-approval-details-window.png follows
      Description of the illustration mouseover-reject-status-approval-details-window.png

      Notice the timestamp that shows when the approval was rejected and any comments that were added explaining why.

      If an expiration duration was set for the manual approval but nobody approves it during the specified interval, the build system automatically rejects the approval. The activities stream displays the reason for the rejection. In addition, the Pipeline Run Summary screen and the notification email that is sent to required approvers also indicate why the approval was rejected.

      Note:

      Currently, you can't resume a pipeline after it has been rejected. You'll need to address and correct the issue(s) that caused an approver to reject completing the pipeline run and then restart the pipeline and approval process.

Notify the Pipeline Approvers

Pipeline approvers are notified in email that an approval is awaiting their action.

When a pipeline encounters a Manual Approval item, the pipeline run pauses and an email notifying approvers that they need to take action is sent. The Pipeline Queue page shows who triggered the build (if triggered manually), the pipeline name, the run number, if it was scheduled, and progress, which shows, "Waiting for approval". If you hover over it, you'll see a different message, depending on your role:
  • If you're not an approver, you'll see "Not waiting for your approval. Approvals pending:", followed by a list of the approvers.
  • If you're an optional approver, you'll see "Waiting for approval. Go to pipeline name run number"
  • If you're a required approver, you'll see "You are a required approver. Go to pipeline name run number"

If you’re an approver, you can click Waiting for approval to go to the Pipeline Run page, which shows all the approvers, who has already approved, and so on, as shown:
Description of manualapproval.png follows
Description of the illustration manualapproval.png

If you approve or reject from here (by right-clicking the Approval node), any comments you supply will be added to the final email that all approvers receive.

Note:

If you are not a required approver and you approve the job (either from here or through email), the pipeline remains paused until all required approvers have signed off. If you reject the job, this run of the pipeline is canceled.
As an approver, there are a few tasks that you need to do to ensure that you can receive email notifications about pipeline approvals:
  • Make sure you verified your email address or you won't receive any VB Studio email notifications at all.

    You don't want to see this message.

    The Profile tab under User Preferences for Alex Admin. The Not Verified error message indicates that Alex's email address hasn't been verified yet. He needs to locate the original verification email from VB Studio of click the Re-send email button to have it resent to him.

  • Make sure you enabled notifications for Build activities and that you're also set up to include your own updates.

    The check boxes encircled in red need to be selected.

    The Notifications tab under User Preferences for Alex Admin. The Build activities and Include my own updates check boxes are selected. Other check boxes (Issues updates, attachments, comments; Merge Request updates and comments; Project updates) are also selected.

To check both items, click the user avatar and select Preferences. See Configure Your Global Email Notifications for additional information about these items that you need to check and potentially address.

Click on link in email and it'll take you to the pipeline's Run page or from the Build page's Pipeline Queue tab go to the Waiting for approval link in the Progress column. Because you're the approver, you can see the link. If you're not one of the approvers, you'll see the same message but it won't be a link. If you are an approver and you click the link, you'll go to the Pipeline Designer graph. Hover over the approval item to see its status, then right-click and select the Approve/Reject Details option. If you approved it, the Pipeline approve submitted message is displayed. Once the required number of approvers have submitted an approval, the pipeline starts back up and continues running, the approval node turns green (signifying completion), and the pipeline continues by executing the next downstream task.

There are several places in the pipelines interface where approvers are subtly notified about pending approvals.
  • They can see the pipeline's flow from the Pipeline Run page before approving or rejecting it.
  • The Pipeline Queue tab shows pipelines runs that are either running or are waiting for some action, such as an approval. If a pipeline is in the waiting state, an approval (or multiple ones) is needed.
  • From the Pipeline Queue page, you can sort by the Progress column, to see all the pipelines "Waiting for approval".
  • The notification email's subject line may show, for example, "Pipeline run 4 for pipeline ManualApproval07 requires approval to proceed". If you click the "4" link in the email, you'll be taken to the page where you can right-click the Approval node and select the Approve/Reject Details context menu item.