Adding an Integrations Stage

An Integrations stage invokes an Oracle Cloud Infrastructure (OCI) function. This stage can be used to run code or custom logic in a serverless manner. For example, you can write a function that validates your application in the staging environment and if successful, deploy the application to the production environment.

Before you begin, you must have a deployment pipeline defined and you must create a function that is invoked when the pipeline is run.

Required IAM Policy

Each service in OCI integrates with Identity and Access Management (IAM) for authentication and authorization. To grant users permission to access the DevOps deployment pipelines and other resources, you have to create dynamic groups and IAM policies.

For creating dynamic groups and policies for deployment pipelines, see Deployment Pipeline Policies. For more details, see DevOps IAM Policies.

For accessing DevOps using the Oracle Cloud Console, REST API, and CLI, see Accessing DevOps.

Using the Console

  1. Open the navigation menu and click Developer Services. Under DevOps, click Projects.
  2. Select a project and a pipeline associated with that project.
  3. To add the Integrations stage sequentially or in parallel, click the + icon and select Add stage.
  4. Select Integrations - Invoke Function, and then click Next.
  5. Enter a name and optional description for the stage.
  6. For Environment, select an existing function to invoke.

    The read-only Function name field displays the function that is called in the pipeline.

  7. (Optional) To select and add artifacts to the stage, click Select Artifact.

    Select an existing artifact resource from your DevOps project. The artifact must be generic (universal) file type. Parameters in the artifact must be in JSON format and can have placeholders. You must select the "Yes, substitute placeholders" option when configuring the DevOps artifact resource to substitute the placeholders with the argument value during deployment. For more information, see Configuring Parameters.

    Here's an example of the generic artifact content to pass two user-defined parameters and their values:
    • Parameters: test_name, app_version
    • Values: {"test_name":"verify_production", "app_version":"${app_version}"}
  8. For Stage run mode, select to run asynchronously or synchronously.

    If you select Run asynchronously, the service invokes the function but does not wait for the function to complete. On selecting Run synchronously, the service invokes the function and waits for the function to complete.

  9. Select to disable or enable validation.

    If the validation is enabled, then the service verifies the return value of the function. The return value is a UTF-8 string literal, true or false. If the return value is true, then the stage is marked as Succeeded, otherwise the stage is marked as Failed.

    If the validation is disabled, then the service does not verify the return value.

    Validation occurs only if you have selected the option “Run synchronously” for stage run mode.

  10. (Optional) To add tags to the pipeline, click Show tagging options. Tagging is a metadata system that lets you organize and track the resources in your tenancy.

    If you have permissions to create a resource, you also have permissions to add free-form tags to that resource.

    To add a defined tag, you must have permissions to use the tag namespace.

    For more information, see Resource Tags.

  11. To add the Integrations stage to the pipeline, click Add.
To deploy the build output to the target environment, run the deployment pipeline.

To automatically trigger a deployment from the build pipeline, you can add a Trigger Deployment stage to the build pipeline.

Using the CLI

To invoke a function in the pipeline, run the create-invoke-function-stage command:

oci devops deploy-stage create-invoke-function-stage

Required parameters for the create-invoke-function-stage command:

  • --function-environment-id
  • --is-async
  • --is-validation-enabled
  • --pipeline-id
  • --stage-predecessor-collection

To get all the commands for deploy-pipeline and deploy-stage:

oci devops deploy-pipeline -h
oci devops deploy-stage -h

To get help for the create-invoke-function-stage command:

oci devops deploy-stage create-invoke-function-stage -h

Using the API

To invoke a function in the pipeline, use the CreateDeployStage operation. For deployStageType attribute, specify the INVOKE_FUNCTION value.