Scope service workflow

This guide walks you through how to implement the workflows that power your agent-backed scope. Workflows define how your scope responds to actions like create, start_blue_green, or delete.

You’ll define YAML workflow files and run them using the np service workflow CLI commands.

💡 If you're using one of our production-ready scopes from the how-to guides, most of this setup is already taken care of. Use this page if you're building your own workflows or want to customize an existing one.

1. Create workflow files

Each action your scope supports (e.g. create, start_blue_green) must have a matching workflow file.

These workflows are written in .yaml and specify the commands or scripts that should run when an action is triggered.

Where to place workflow files

Use the following file paths for each workflow:

Action	Triggered when...	File path
Create scope	The scope is created	$SERVICE_PATH/scope/workflows/create.yaml
Update scope	The scope is updated (currently unused)	$SERVICE_PATH/scope/workflows/update.yaml
Delete scope	The scope is deleted	$SERVICE_PATH/scope/workflows/delete.yaml
Start initial	First deployment or restart	$SERVICE_PATH/deployment/workflows/initial.yaml
Start blue green	New blue-green deployment	$SERVICE_PATH/deployment/workflows/blue_green.yaml
Switch traffic	Traffic is being shifted during blue-green	$SERVICE_PATH/deployment/workflows/switch_traffic.yaml
Finalize deployment	Blue-green deployment is finalized	$SERVICE_PATH/deployment/workflows/finalize.yaml
Rollback deployment	Blue-green deployment is canceled	$SERVICE_PATH/deployment/workflows/rollback.yaml
Delete deployment	Deployment is removed	$SERVICE_PATH/deployment/workflows/delete.yaml
Read logs	Logs are requested	$SERVICE_PATH/log/workflows/log.yaml
Get metrics	Metrics are requested	$SERVICE_PATH/metric/workflows/metric.yaml
List instances	Instance list is requested	$SERVICE_PATH/instance/workflows/list.yaml

Need a refresher on the action types? See the action spec reference.

Workflow file format

Here's a basic example:

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

Example with configuration, pre, and post steps

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..."

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.

2. Run your scope service workflows

Use the CLI to execute a workflow manually.

np service workflow exec --workflow $path_to_workflow_file

This converts your .yaml file into a bash script and runs each step in sequence using &&.

Available flags

Flag	Description	Required
--workflow	Path to the workflow YAML file	Yes
--build-context	Builds a context object with related entities (e.g. scope, deployment, release)	Recommended
--values	Path to a YAML file with parameter values for all steps	Recommended
--overrides	Merges or replaces steps in the workflow file using a separate override file	Optional
--dry-run	Outputs the resulting YAML instead of executing the workflow	Optional

Example

• Basic

  np service workflow exec --workflow ./deployment/workflows/create.yaml

• With overrides and shared parameters:

  np service workflow exec \
    --workflow ./deployment/workflows/create.yaml \
    --values ./values.yaml \
    --overrides ./deployment/overrides.yaml

3. Build the action context (optional)

You can use the --build-context flag or set the NP_ACTION_CONTEXT environment variable to inject all related entities into your workflow.

export NP_ACTION_CONTEXT=your_context_here

or

np service workflow --build-context

This builds a JSON object containing all entities related to a scope or deployment action.

Available flags

Flag	Description	Required
--notification	- Provides the notification payload that triggered the service action. - Use this if NP_ACTION_CONTEXT is not set.	Optional
--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.	Optional

Example

Below there are some example but you can check our Event payloads docs for more details.

Click to view example scope context

{
  "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"
    }
  }
}

Click to view example deployment context

{
"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
      }
    ]
  }
}

What's next?

Want to dynamically merge or modify your workflow files? Head over to Override scope workflows.