Skip to main content

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 Tutorials hub, 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:

ActionTriggered when...File path
Create scopeThe scope is created$SERVICE_PATH/scope/workflows/create.yaml
Update scopeThe scope is updated (currently unused)$SERVICE_PATH/scope/workflows/update.yaml
Delete scopeThe scope is deleted$SERVICE_PATH/scope/workflows/delete.yaml
Start initialFirst deployment or restart$SERVICE_PATH/deployment/workflows/initial.yaml
Start blue greenNew blue-green deployment$SERVICE_PATH/deployment/workflows/blue_green.yaml
Switch trafficTraffic is being shifted during blue-green$SERVICE_PATH/deployment/workflows/switch_traffic.yaml
Finalize deploymentBlue-green deployment is finalized$SERVICE_PATH/deployment/workflows/finalize.yaml
Rollback deploymentBlue-green deployment is canceled$SERVICE_PATH/deployment/workflows/rollback.yaml
Delete deploymentDeployment is removed$SERVICE_PATH/deployment/workflows/delete.yaml
Read logsLogs are requested$SERVICE_PATH/log/workflows/log.yaml
Get metricsMetrics are requested$SERVICE_PATH/metric/workflows/metric.yaml
List instancesInstance 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​

FlagDescriptionRequired
--workflowPath to the workflow YAML fileYes
--build-contextBuilds a context object with related entities (e.g. scope, deployment, release)Recommended
--valuesPath to a YAML file with parameter values for all stepsRecommended
--overridesMerges or replaces steps in the workflow file using a separate override fileOptional
--dry-runOutputs the resulting YAML instead of executing the workflowOptional

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​

FlagDescriptionRequired
--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 are some examples, 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.