17 Bundles and CI/CD (Preview)

Bundles define how Oracle AI Data Platform Workbench resources are packaged, versioned, shared, and deployed across workspaces and environments.

You can create bundles for jobs and agents. A bundle is created in a Git folder so that the bundle files can be committed and pushed to a Git repository. The resources that you include in the bundle can come from any location in the workspace. If the selected resources reference supporting files or dependencies, such as notebooks, scripts, or compute, those references are included in the bundle so the resources can be deployed in another environment without manually recreating the same components.

You create bundles from your workspace and select the Oracle AI Data Platform Workbench resources to include at the time of creation. Existing bundles can be modified to add or remove resources. Bundling resources allows you to group related jobs and agents together and deploy them to other environments with their dependencies intact.

You can commit and push bundles to your Git repository through your Git folders. Users can then pull the bundles into their own environments and deploy them. Changes to bundle files are available to other environments after the changes are committed and pushed to the Git repository. Whenever users pull the updated bundle from the Git repository, they receive the latest committed resource files.

Bundle Concepts

Concept Meaning User Action
Git folder An AI Data Platform folder connected to a Git repository and branch. Bundles can be created only in Git folders. Create or open a Git folder before creating a bundle.
Bundle A deployable package that defines selected resources and their dependencies. Create the bundle from the workspace, then select resources such as jobs or agent flows.
Bundle content Generated files that describe resources, variables, target settings, and artifacts required for deployment. Review generated content after create or sync. Commit and push the bundle through Git when ready.
Target An environment or workspace configuration used when deploying the bundle outside the source environment. Provide values that must change by environment, such as workspace key, credential name, token key, or parameter defaults.
Deployed item A resource created or updated by a bundle deployment in the target workspace. Use the Deployment tab to deploy, review deployed items, run jobs, and purge deployed resources when needed.
Sync A bundle action that refreshes bundle resources and dependencies from the latest source resources. Run sync after changing bundled resources, then commit the refreshed bundle files to Git.

Before You Start

Check this list to make sure you have everything you need to start using Git bundles in your AI Data Platform workspace:
  • Create Git credentials and a Git folder that points to the repository and branch used for bundle files.
  • Confirm the source resources are in the workspace and are saved before creating or syncing the bundle.
  • For cross-environment deployment, confirm the target workspace has required permissions and compute capacity.
  • For jobs or notebooks that use secrets, create the required named credentials in the target credential store. Bundle files should reference credentials by name or variable, not contain secret values.
  • Commit and push bundle file changes after creating or syncing a bundle so other environments can pull the latest bundle definition.

Create a Bundle (Preview)

You can bundle Oracle AI Data Platform job and agent resources to create a package that can be deployed to another Git folder.

  1. Navigate to your workspace.
  2. Click Actions then click Create Bundle.
  3. Provide a name and description for your bundle.
  4. Click Browse and select the Git folder in your workspace where you want to create your bundle.
  5. Select the resources you want to include in the bundle from the listed options.
  6. Click Create.

    Note:

    Bundles are created in Git folders. If the selected location is not inside a Git folder, you cannot use Git to move the generated bundle files to another environment.

What Gets Generated After Bundle Creation (Preview)

After bundle creation, Oracle AI Data Platform writes your generated files into the bundle folder.

The exact file names vary by resource type, but the created bundle usually contains a top-level bundle manifest, resource definitions, artifact folders, and optional override files.

Generated Item Description
aidp_workbench.yaml Bundle manifest. Identifies the bundle, included resources, variables, and target sections used during deployment.
.aidp/resource_origins.yaml Resource definitions. Describe resources such as jobs, notebook tasks, compute references, or agent flows.
.aidp/overrides.yaml Override files or target sections. Hold values that differ by environment, such as workspace identifiers, parameter defaults, credential names, or token keys.
.aidp/aidp.state.json Tracks resources deployed from the bundle. Used by future deploy and purge operations.
jobs/ Job descriptors and job dependencies.
agentflows/ Agent descriptors and agent dependencies.
artifacts/ Artifact folders. Copied code, notebooks, and supporting file artifacts.

Deploy a Bundle (Preview)

You can deploy bundles from a Git folder to share resources and dependencies across workspaces and environments.

  1. Navigate to the bundle you want to deploy in your workspace.
  2. Click the Deployment tab.
  3. Optional: Review target values and overrides, if applicable.
  4. Click Deploy. You are notified when the deployment is complete.

    Note:

    On first deployment, the Deployment tab may show no deployed items until deployment succeeds. After a successful deployment, review the deployed resources, run jobs or agents as needed, and confirm runtime output.

Sync a Bundle (Preview)

You can sync a bundle to update the resources and dependencies in the bundle with the latest changes.

Sync uses the bundle's recorded origin metadata to rebuild the bundle from the source jobs and agent flows that were captured when the bundle was created. The source metadata is stored in .aidp/resource_origins.yaml and must match the requested instance and workspace. The operation refreshes source-controlled bundle content while preserving the bundle identity and runtime metadata.

During sync, the service stages a refreshed bundle snapshot under the bundle .aidp directory, compares existing and staged descriptors, preserves existing variable aliases and override references where possible, merges existing manifest default variables, and then promotes the refreshed source-controlled files back into the bundle root.

Sync preserves environment-specific and deployment runtime files such as .aidp/overrides.yaml and .aidp/aidp.state.json. These files are not replaced by the refreshed source snapshot.

You should sync your bundles when:
  • A bundled notebook, job, agent flow, compute reference, parameter, or dependency changed in the source workspace.
  • A bundled job now points to a different notebook or has updated task parameters.
  • An agent configuration, prompt parameter, model setting, or AI compute dependency changed.
  • You need the Git folder to contain the latest generated bundle files before pushing to another environment.
  1. Navigate to the bundle you want to sync in your workspace.
  2. Click Actions.
  3. Click Sync. You are notified when the sync is complete.

Recommended Promotion Workflow for Bundles

We recommend following a workflow of develop, package, version, pull, configure, deploy, and validate for Git bundles in Oracle AI Data Platform.

Phase Action Result
Develop Create or update notebooks, jobs, compute settings, or agent flows in the source workspace. The source resources contain the latest intended behavior.
Package Create the bundle, or run Sync on an existing bundle. Generated bundle files reflect the current source resources and dependencies.
Version Review, commit, and push the bundle folder through the Git folder. The remote repository contains the deployable bundle definition.
Pull In the target workspace, pull the Git folder changes. The target workspace has the latest bundle files.
Configure Set target-specific values such as workspace key, parameter defaults, credential name, token key, or runtime settings. The bundle is ready for the target environment.
Deploy Open the bundle Deployment tab and click Deploy. Workbench creates or updates the deployed resources.
Validate Run deployed jobs or test deployed agent flows and inspect logs or output. The target environment is verified before promotion continues.

Bundle Variables (Preview)

Use bundle variables when a bundle needs deploy-time values that can change for every target environment without editing the resource definition.

To begin using variables with bundles, you need to define the variable names in the bundle's aidp_workbench.yaml file with default values and, when needed, environment-specific overrides. You then reference those variables from generated definition files.

Example Variable Workflow

  1. Define variable names under defaults > variables in aidp_workbench.yaml.
  2. Optionally define environment-specific values under targets > <environment> > variables in the same aidp_workbench.yaml file.
  3. Use target overrides to set deploy-time values such as a dev region, QA region, production region, schema name, credential name, token key, or parameter default.
  4. When no matching target environment is found, Oracle AI Data Platform uses the default variable value from aidp_workbench.yaml.
  5. Use the variable in any generated definition file, such as a job definition, compute definition, task definition, or other YAML definition file.
  6. Reference the variable with ${var.<<variable_name>>}, replacing <<variable_name>> with the actual variable name defined in aidp_workbench.yaml.
  7. Use resource-specific placeholder syntax in places such as agent prompts or tool definitions when the UI expects a named placeholder.
  8. For temporary deployment-only changes, create .aidp/overrides.yaml and define variable values there.

Bundle Variable Syntax

Variable definitions must be written in aidp_workbench.yaml. Other bundle definition files should only reference the variable name.

Definition Syntax Example
Variable definition in aidp_workbench.yaml 
defaults: 
  variables: 
    <<variable_name>>: <<default_value>> 
defaults: 
  variables: 
    deployment_region: "us-ashburn-1"
Target-specific override inaidp_workbench.yaml 
targets: 
  <<target_name>>: 
    variables: 
      <<variable_name>>: <<target_value>> 
targets: 
  qa: 

   “workbenchid”: “ocid” 
   “workspaceKey”: “key” 

    variables: 
      deployment_region: "us-phoenix-1"
Variable reference in a definition file ${var.<<variable_name>>} value: "${var.deployment_region}"
Named placeholder in an agent prompt or tool field {{variable_name}} Generate a summary about {{topic}}.

Example: Job Parameter Variable

The following example defines one variable and passes it into a job parameter. The resource can remain unchanged while the variable value changes in the bundle configuration.
bundle: 
  name: namedVariableJobDemo 
resources: 
  jobs: 
    - namedVariableJobDemo 
defaults: 
  variables: 
    job_param_value_default: "cloud data governance" 

jobs: 
  namedVariableJobDemo: 
    tasks: 
      - taskKey: Task_956691 
        parameters: 
          - name: param_key 
            value: "${var.job_param_value_default}"

A notebook task can read the resolved value through the parameter name used by the job:

param_value = odiUtils.parameters.getParameter("param_key", "fallback value") 
print(param_value)

Example: aidp_workbench.yaml Variable Definition

This example defines the variable agent_topic_default in aidp_workbench.yaml. The default value applies when no matching target environment is found, or when no selected environment or temporary override supplies the variable. Each target can override the same variable name for that workspace.
defaults: 
  variables: 
    agent_topic_default: "Oracle AI Data Platform" 

targets: 
  dev: 
    - aidp_ocid: "ocid1.aidataplatformdev.oc1.iad.exampledev" 
      workspace_key: "6271b138-6f2c-4e8c-a9e5-013e17079955" 
      variables: 
        agent_topic_default: "AIDP Dev Workspace" 
  qa: 
    - aidp_ocid: "ocid1.aidataplatformdev.oc1.iad.exampleqa" 
      workspace_key: "daa0e9b5-f8d7-4ae8-b728-2984e68a74c0" 
      variables: 
        agent_topic_default: "AIDP QA Workspace" 
  prod: 
    - aidp_ocid: "ocid1.aidataplatform.oc1.iad.exampleprod" 
      workspace_key: "83be5b8c-bb8d-4ec4-a8fb-16b50b0e4d4c" 
      variables: 
        agent_topic_default: "AIDP Production Workspace"

Any bundle definition file that supports bundle variables can then reference the same variable name. For example:

tasks/agentTopic.task.yaml 

parameters: 
  - name: topic 
    value: "${var.agent_topic_default}"

Example: File Names and Resolution

In a generated bundle, the variable definition and the resource that uses the variable can be in different files. When you promote or copy the example through Git, include the whole bundle folder so the manifest, job definition, and artifacts stay together. 
testNamedVarBundleJob/ 
  aidp_workbench.yaml 
  jobs/ 
    namedVariableJobDemo.job.json 
  artifacts/ 
    namedVarNotebookDemo.ipynb
File What It Contains Variable or Resolved Value
aidp_workbench.yaml Defines the variable under defaults > variables and optional target overrides. Variable: job_param_value_default.
jobs/namedVariableJobDemo.job.json Uses the variable as the value for job parameter param_key. Reference: ${var.job_param_value_default}.
artifacts/namedVarNotebookDemo.ipynb Reads the resolved job parameter at runtime. Notebook reads param_key after resolution.
For example, the bundle manifest can define the default and the target overrides in aidp_workbench.yaml:
defaults: 
  variables: 
    job_param_value_default: "cloud data governance" 
targets: 
  dev: 
    variables: 
      job_param_value_default: "space tourism" 
  qa: 
    variables: 
      job_param_value_default: "data quality validation" 
  prod: 
    variables: 
      job_param_value_default: "customer operations"

The job definition can then use that same variable name in jobs/namedVariableJobDemo.job.json. The same syntax can be used in job definitions, compute definitions, task definitions, and other generated YAML definition files that support bundle variables:

"parameters": [ 
  { 
    "name": "param_key", 
    "value": "${var.job_param_value_default}" 
  } 
]
Deployment Target Variable Resolution Notebook Receives
No matching target Uses default from aidp_workbench.yaml. param_key = cloud data governance
dev Uses dev target override. param_key = space tourism
qa Uses qa target override. param_key = data quality validation
prod Uses prod target override. param_key = customer operations

Resolution Order

When .aidp/overrides.yaml supplies a variable value, AI Data Platform uses that temporary value for the next deployment. Otherwise, AI Data Platform resolves the variable from the selected target first. If no matching target environment is found, or the selected target does not override the variable, AI Data Platform falls back to defaults > variables in aidp_workbench.yaml. If no value is available for the referenced variable, deployment or job execution can fail before the notebook fallback value is used.

Temporary Overrides for the Next Deployment

The definitions in aidp_workbench.yaml are sufficient for normal bundle promotion. If a user needs to override a variable temporarily, create .aidp/overrides.yaml in the bundle folder and define the variable values there. AI Data Platform uses those values during the next deployment. 

.aidp/ 
  overrides.yaml
variables: 
  agent_topic_default: "tuesday"
File Example Value When Used
aidp_workbench.yaml defaults Oracle AI Data Platform Used when no matching target or override file supplies the variable.
aidp_workbench.yaml target dev AIDP Dev Workspace Used when deploying to dev and no temporary override is present.
.aidp/overrides.yaml tuesday Used as a temporary value during the next deployment.

Note:

Use .aidp/overrides.yaml for temporary deployment values. Keep durable defaults and environment-specific values in aidp_workbench.yaml so the bundle remains reproducible through Git.

Example: Agent Prompt Variable

For agent flow prompt text or tool definitions that support named placeholders, use double braces around the variable name.

Prompt text: 
You are a demo assistant. For the given {{topic}}, generate 3 short bullet points explaining why it matters. 

Tool parameter: 
Name: /{{topic}} 
Default value: sunday

Note:

As a best practice, you should use variables for values that are expected to change across deployments. Avoid embedding environment-specific values directly into notebooks, jobs, or agent flow text when a variable can carry the value instead.

Example: Workflow without Compute

You can create a bundle for a workflow that doesn't automatically create a compute cluster as part of deployment. First, create a variable in aidp_workbench.yaml: 

defaults:
 variables:
  job_compute_key: "select_compute"
Next, in the jobs/ folder, locate the job file <JobName>.job.json. Edit the job file replace the "clusterKey" value with the new created variable:
"clusterKey" : "${var.job_compute_key}",

Bundle Variables and Credential Store (Preview)

You can use variables with the credential store when a bundled job or notebook needs to look up a secret at runtime.

Your variables should carry the credential name and token key. The actual secret value must stay in the target credential store and should not be committed to Git.

Example Workflow: Using Variables with Credential Store

  1. Create the credential and token key in credential store.
  2. Define variables for the credential name and token key.
  3. Pass those variables into the job or notebook as parameters.
  4. At runtime, the notebook reads the parameters and calls the credential API to retrieve the secret. If the credential name, token key, or permissions are wrong, the job can fail with a credential lookup error.

Note:

Do not document or commit secret values in bundle files. Bundle configuration should reference credential names, token keys, and target variables; the credential store remains the source of secret material.

Example: Credential Name and Token Key Variables

bundle: 
  name: credentialVariableDemoBundle 
resources: 
  jobs: 
    - credentialLookupJob 
defaults: 
  variables: 
    cred_key: default_credential_name 
    token_key: default_token_key 
targets: 
  dev: 
    workspace_key: dev_workspace 
    variables: 
      cred_key: dev_credential_store_entry 
      token_key: dev_token 
  qa: 
    workspace_key: qa_workspace 
    variables: 
      cred_key: qa_credential_store_entry 
      token_key: qa_token 
  prod: 
    workspace_key: prod_workspace 
    variables: 
      cred_key: prod_credential_store_entry 
      token_key: prod_token 

jobs: 
  credentialLookupJob: 
    tasks: 
      - taskKey: Task_854239 
        parameters: 
          - name: cred_key 
            value: "${var.cred_key}" 
          - name: token_key 
            value: "${var.token_key}"

The notebook reads the parameter values and uses them to look up the secret from the credential store: 

cred_name = odiUtils.parameters.getParameter("cred_key", "defaultCredValue") 
token_name = odiUtils.parameters.getParameter("token_key", "defaultTokenValue") 

secret = aidpUtils.secrets.get(name=cred_name, key=token_name) 
if secret: 
    print("Credential lookup succeeded") 
else: 
    raise Exception("Credential lookup failed")
Environment cred_key Value token_key Value Credential Store Requirement
dev dev_credential_store_entry dev_token Create dev_credential_store_entry with key dev_token.
qa qa_credential_store_entry qa_token Create qa_credential_store_entry with key qa_token.
prod prod_credential_store_entry prod_token Create prod_credential_store_entry with key prod_token.

Purge a Bundle (Preview)

You can purge a deployed bundle to remove the bundle resources from your workspace.

  1. Navigate to the bundle you want to purge resources for in your workspace.
  2. Click the Deployment tab.
  3. Click Purge.
  4. Enter Purge in the prompt. Click Purge.

Troubleshooting Bundles (Preview)

If you encounter problems when creating and managing Git bundles, check the following list of issues for potential solutions.

Symptom Likely Cause Recommended Action
Create Bundle is unavailable or the bundle cannot be created. The user is not in a Git folder, or lacks required workspace permissions. Navigate to a Git folder and confirm the user can create workspace resources.
Sync completes, but another environment does not see the update. The refreshed bundle files were not committed, pushed, or pulled into the target Git folder. Commit and push from the source Git folder, then pull in the target workspace before deploying.
Deployment tab shows no deployed items. The bundle has not been deployed yet, or deployment did not complete successfully. Click Deploy and wait for the completion notification. Review logs if deployment fails.
Deployed job fails with a credential lookup error. The target credential name, token key, or access permission does not match the bundle configuration. Create the credential in the target credential store or update target variables before redeploying.
Agent flow deployment fails or starts with inactive compute. The target environment may not have compatible AI compute, region, model, or dependency settings. Review target overrides, compute status, model availability, and deployment logs.
Changes to a source notebook or agent flow are not reflected after deployment. The bundle was deployed without first syncing from the updated source resource. Run Sync on the bundle, commit and push the refreshed bundle files, pull them in the target, then deploy again.