Run a scope service workflow

Once you've created a scope service spec and defined its actions, the next step is to implement them through workflows.

For that, you'll need to:

1. Define workflow files for your scope actions
2. Run your scope service workflow.

Before you start

• Make sure to have the nullplatform CLI installed.
• Create an API key with agent, developer, ops, and secrets-reader permissions.

1. Define workflow files for your scope actions

Create a .yaml workflow files that define the action steps of your scope service.

Note: You need to create one workflow file for each action spec you defined for your scope service.

Workflows

Action	Runs when...	Description	File path
Create Scope	the scope is created	Creates the DNS record and ingress for the scope.	$SERVICE_PATH/scope/workflows/create.yaml
Update Scope	the scope is updated	Currently unused. All updates are handled during deployment, so this workflow remains empty.	$SERVICE_PATH/scope/workflows/update.yaml
Delete Scope	the scope is deleted	Removes the DNS record and ingress.	$SERVICE_PATH/scope/workflows/delete.yaml
Start Initial	creating a deployment of type initial	Deploys the application and directs traffic using the ingress.	$SERVICE_PATH/deployment/workflows/initial.yaml
Start Blue Green	creating a deployment of type blue green	Deploys a new version and configures the ingress to route traffic to both versions.	$SERVICE_PATH/deployment/workflows/blue_green.yaml
Switch Traffic	changing traffic distribution in a blue green deployment	Updates the ingress to modify traffic routing between blue and green versions.	$SERVICE_PATH/deployment/workflows/switch_traffic.yaml
Rollback Deployment	a blue green deployment is canceled	Deletes the green deployment and routes all traffic back to the blue version.	$SERVICE_PATH/deployment/workflows/rollback.yaml
Finalize Deployment	a blue green deployment is finalized	Deletes the blue deployment and routes all traffic to the green version.	$SERVICE_PATH/deployment/workflows/finalize.yaml
Delete Deployment	stopping or deleting the scope	Removes the active deployment and updates the ingress to indicate no active backend is deployed.	$SERVICE_PATH/deployment/workflows/delete.yaml
Read Logs	logs for the scope are requested	Returns the scope’s logs.	$SERVICE_PATH/log/workflows/log.yaml
Get Metrics	metrics for the scope are requested	Returns performance and usage metrics.	$SERVICE_PATH/metric/workflows/metric.yaml
List Instances	listing the active instances	Returns a list of currently active instances.	$SERVICE_PATH/instance/workflows/list.yaml

Action specification reference

See our lifecycle actions reference docs if you need more info.

Workflow file format

The workflow file should follow this format:

steps:
 - name: execute a bash command
   type: command
   command: echo "executing a bash command..."
 - name: execute a script
   type: script
   file: path-to-script-to-execute
 - name: execute with sub-steps
   type: workflow
   steps:
     ... list of commands, scripts, or workflows

Additional step configurations

You can further configure the steps in your workflow file with the following keys:

• configuration - Defines key-value pairs for additional arguments/parameters to be passed to scripts.
• pre - A command or script executed before the defined step.
• post - A command or script executed after the defined step.

Here's an example of a script-based step that uses configuration, pre, and post hooks:

steps:
 - name: deployment
   type: script
   file: deployment.sh
   configuration:
     env: prod
     template: my-deployment-template.yaml.tpl
   pre:
     type: command
     command: echo "setup deployment..."
   post:
     type: command
     command: echo "validate deployment is ready..."

2. Run your scope service workflows

Execute your workflow file to apply the action steps in sequence.

This command converts your workflow steps into a Bash script and runs them in sequence using &&.

np service workflow exec --workflow $path_to_workflow_file

The command accepts the following flags:

Flag	Description	Required
--workflow	Converts the provided configuration file into a single executable Bash script. Accepts a file path.	Yes
--build-context	Builds an object that includes all entities related to an action in a custom scope.	Recommended
--values	Specifies a YAML file with parameters that apply across all workflow steps. Useful for setting shared variables like environment or configuration values.	Recommended
--dry-run	Returns a final YAML file, showing the applied overrides to the base workflow.	No
--overrides	Merges or overrides the base workflow configuration using an additional config file. Accepts a file path. See Overriding scope service workflows.	No

Example execution

In the basic example, the generated Bash command will look like this:

bash -c 'echo "executing a bash command..." && source path-to-script-to-execute'

With additional configurations in your steps, the execution will look like:

bash -c 'echo "setup deployment..." && ENV=prod TEMPLATE=my-deployment-template-yaml.tpl source deployment.sh && echo "validate deployment is ready..."'

Build the action context for a scope or deployment

Prerequisites

Make sure the NP_ACTION_CONTEXT environment variable is set:

export NP_ACTION_CONTEXT=action_context_variable

Use the --build-context flag to generate a context object that includes all entities related to a scope or deployment action. This context can be used for either:

• scope actions
• deployment actions

np service workflow --build-context

The command flag accepts the following flags:

Flag	Description	Required
--notification	- Provides the notification payload that triggered the service action. - Use this if NP_ACTION_CONTEXT is not set.	No
--include-secrets	- Includes secret values in the generated context. - Required The agent must have an API key with agent, developer, ops, and secrets-reader permissions.	No

Example outputs

For scope actions, it returns entities such as account, namespace, application, and scope.

JSON output for scope actions

{
  "account": {
    "id": 2,
    "nrn": "organization=1:account=2",
    "name": "account-name",
    "slug": "account-name",
    "organization_id": 1,
    "status": "active",
    "repository_prefix": "prefix",
    "repository_provider": "github",
    "metadata": {}
  },
  "namespace": {
    "id": 3,
    "nrn": "organization=1:account=2:namespace=3",
    "name": "namespace-name",
    "slug": "namespace-name",
    "account_id": 2,
    "status": "active",
    "metadata": {}
  },
  "application": {
    "id": 4,
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "name": "application-name",
    "slug": "application-name",
    "status": "active",
    "auto_deploy_on_creation": false,
    "is_mono_repo": false,
    "metadata": {},
    "namespace_id": 4,
    "repository_app_path": null,
    "repository_url": "https://github.com/github-account/application-name",
    "tags": {},
    "template_id": 1234
  },
  "scope": {
    "id": 5,
    "nrn": "organization=1:account=2:namespace=3:application=4:scope=5",
    "name": "scope-name",
    "slug": "development-uruguay",
    "application_id": 4,
    "type": "custom",
    "status": "stopped",
    "capabilities": {
      ...
    },
    "dimensions": {
      "country": "uruguay",
      "environment": "development"
    }
  }
}

For deployment actions, it returns entities such as deployment, asset, release, and parameters.

JSON output for deployment actions

{
"deployment": {
    "id": 6,
    "release_id": 9,
    "scope_id": 5,
    "nrn": "organization=1:account=2:namespace=3:application=4:scope=5:deployment=6",
    "status": "creating",
    "strategy": "blue_green",
    "strategy_data": {
      "desired_switched_traffic": 10,
      "switch_traffic_step": true,
      "switched_traffic": 0
    },
  },
  "release": {
    "id": 9,
    "application_id": 4,
    "build_id": 7,
    "nrn": "organization=1:account=2:namespace=3:application=4:release=9",
    "semver": "0.0.1",
    "status": "active"
  },
  "asset": {
    "id": 8,
    "build_id": 7,
    "name": "my-asset",
    "type": "docker-image",
    "url": "...",
    "platform": "arm",
    "nrn": "organization=1:account=2:namespace=3:application=4:build=7:asset=8"
  },
  "parameters": {
    "paging": {
      "limit": 30,
      "offset": 0
    },
    "results": [
      {
        "encoding": "plaintext",
        "id": 10,
        "name": "param-1",
        "nrn": "organization=1:account=2:namespace=3:application=4",
        "read_only": false,
        "secret": false,
        "type": "environment",
        "values": [
          {
            "created_at": "2025-04-16T17:23:30.757Z",
            "dimensions": null,
            "external": null,
            "id": "11",
            "nrn": "organization=1:account=2:namespace=3:application=4",
            "value": ""
          }
        ],
        "variable": "PARAM VALUE",
        "version_id": 11
      }
    ]
  }
}