Command Specification

The command specification contains shell commands and settings that are run during a deployment. The command specification is written in YAML. The file content can be specified inline or the spec can be stored in an Artifact Registry repository.

The command specification is organized into the following sections:

Setup of environment variables.
Input artifacts.
Steps to run in sequence.

Command Specification Syntax

version: 0.1
component: command
timeoutInSeconds: 10000
shell: bash
failImmediatelyOnError: true
env:
  variables:
    key: "value"
    key: "value"
  vaultVariables:
    key: "secret-id"
 
inputArtifacts:
  - name: artifact-name
    type: GENERIC_ARTIFACT
    artifactId: "artifact-ocid"
    registryId: OCID of the Artifact Registry
    path: path of the artifact in the Registry
    version: version of the artifact
    location: target-location
  - name: artifact-name
    type: URL
    url: downloadable link
    location: target-location
 
steps:
  - type: Command
    name: step-name
    shell: shellType
    timeoutInSeconds: 650
    failImmediatelyOnError: true
    command: command
    onFailure:
      - type: Command
        command: |
          command
          command
        timeoutInSeconds: 400
 
  - type: Command
    name: step-name
    command: |
      command
      command
      command
    onFailure:
      - type: Command
        command: |
          command
        timeoutInSeconds: 400

Command Specification Parameters

Following are the command specification parameters and their details:


Parameter	Description
`version`	Mandatory. Indicates the command specification version. A missing or invalid version causes Shell stage failure. Supported value is `0.1`.
`component`	Mandatory. Indicates a particular component in DevOps. A missing or invalid value causes failure of the stage. Supported value is `command`.
`timeoutInSeconds`	Optional. Specifies the timeout for the whole command specification file. Each 'step' can also optionally have its own timeout value. If a value isn't specified, then the default value of 8 hours is used. The maximum allowed value is 8 hours.
`shell`	Optional. Specifies the shell to be used at the command specification global level. The value can be optionally overridden at the 'step' level. Allowed values are `/bin/sh` and `bash`. If not specified, then the default value of `bash` is used.
`failImmediatelyOnError`	Optional. Specifies whether the deployment must continue if any command in the step fails with a nonzero exit value. If not specified, then the default value is `false` and the step continues. Allowed values are `true` and `false`. OCI recommends setting the value of this attribute to `true`.
`env`	Optional. You can define custom variables. Three types of variables are supported: env/variables: Optional. The key must be a string and POSIX environment variable compliant. The value can be any string. The scope of this variable is the execution of the command specification file. Any change to the value of the variable is visible in the subsequent steps. These variables are available as environment variables for all the steps inside the command specification file. If the value of the variable contains new line(\n) or carriage return(\r) character, then they're replaced with space in the subsequent steps. env/vaultVariables: Optional. The key must be a string and POSIX environment variable compliant. The value must be an OCID of the secret from the vault. The vault and pipeline must be of the same tenancy. The tenancy must have an appropriate policy to allow deployment pipeline resources to access the secret. The scope of this variable is the execution of the command specification file and is available to all the steps in the file. The value for these variables is retrieved from the vault and made available as environment variables for all the steps inside the command specification file. env/exportedVariables: Optional. A list of variables can be declared here. The name of the variable must be a string and POSIX environment variable compliant. The value can be assigned in any of the steps inside the command specification file. The scope of this variable is the deployment pipeline. Any exported variable is available only in Shell stages of the same pipeline.
`inputArtifacts`	Optional. Used to define a list of input artifacts that 's required for running the current Shell stage. Supports generic artifacts from Artifact Registry. The parameters are as follows: *inputArtifacts//url: Optional. The input artifact external downloadable HTTP URL must be provided. The URL must be publicly available. Currently authentication/authorization isn't supported. inputArtifacts//name: Mandatory. This name is used to refer the artifacts in command execution. inputArtifacts//location: Mandatory. A destination path of the local file system where the input artifact needs to be downloaded. The path can be specified in one of these methods: `${OCI_PRIMARY_SOURCE_DIR}/pom.xml` `${OCI_WORKSPACE_DIR}/[source-name]/pom.xml` `/workspace/[source-name]/pom.xml` Relative path from project home, `pom.xml` With any one of the values, the input artifact is downloaded to the primary source home directory with a file name, `pom.xml`. Location does not support `exportedVariables` or pipeline variables. inputArtifacts//type: Mandatory. The type of the input artifact that has to be downloaded. Allowed values are `URL` and `GENERIC_ARTIFACT`. inputArtifacts//artifactld: Mandatory. The OCID of the artifact. If you have provided the OCID, then the deployment pipeline ignores the registryId, path, and version. inputArtifacts//registryld: Mandatory. The OCID of the Artifact Registry. inputArtifacts//path: Mandatory. The destination path of the artifact. inputArtifacts//version: Mandatory. The version of the artifact. Note:* For `GENERIC_ARTIFACT` type of input artifact, you can provide as a mandatory parameter either OCID of the artifact or a combination of registry ID, path, and artifact version.
`steps`	Mandatory. This section defines a list of steps that needs to be run. *steps//type: Mandatory. Specifies the type of the step. Supports the following values: `Command` steps//name*: Optional. A user-friendly name for the step.

Step Types

Command


Attribute name	Description
`command`	Both single line and multiple line commands are supported. All the commands specified in one step are run in the same shell session. Based on the `steps/*/shell` value, commands can either be shell or bash. Fail fast isn't enabled. For the step to be successful, output of the last command in a step is considered. If the last command exit code is 0, then the step is considered as successful.
`timeoutInSeconds` (Optional)	Specifies the timeout for the step. If not provided, then the value is inherited from the global `timeoutInSeconds` parameter. The maximum allowed value is 8 hours.
`shell` (Optional)	Specifies the shell type of the current step. If not specified, then the value is inherited from the global `shell` parameter. Allowed values are `/bin/sh` and `shell`.
`onFailure` (Optional)	A list of steps that must be run on failure to gracefully exit the Shell stage. Run if the corresponding step fails, and after execution, the command specification is exited. Handling the failure doesn't affect the status of the Shell stage. If any one of the steps fails, then the Shell stage status remains `failed`, although handled using the `onFailure` block.
`failImmediatelyOnError` (Optional)	Specifies whether the deployment must continue if any command in the step fails with a nonzero exit value. If not specified, then the default value is `false` and the step continues. Allowed values are `true` and `false`. OCI recommends setting the value of this attribute to `true`. The `failImmediatelyOnError` attribute value defined under `steps` takes precedence over the same attribute value defined outside the `steps`.

Predefined System Variables

DevOps provides a set of predefined system variables with default values that you can use in the command specification.


Variable	Description
`OCI_DEPLOYMENT_ID`	The OCID of the current deployment.
`OCI_PIPELINE_ID`	The OCID of the current deployment pipeline.
`OCI_RESOURCE_PRINCIPAL_RPST`	Resource principal token.
`OCI_RESOURCE_PRINCIPAL_VERSION`	Resource principal version.
`OCI_CLI_AUTH`	Preconfigured OCI CLI AUTH to use resource principal.
`OCI_RESOURCE_PRINCIPAL_REGION`	Resource principal region.
`OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM`	Resource principal private key path.

Command Specification Example

Example: Create an OKE namespace.