--- sidebar_label: Scope service workflow toc_max_heading_level: 3 doc_id: 44c53665-9310-4914-8d93-18b579fede5a description: >- Guide for implementing YAML workflows that power agent-backed scope actions like create, deploy, and delete. keywords: - workflows - agent-backed scopes - YAML - deployment - CLI commands --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # 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](/docs/tutorials), 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](/docs/agent-backed-scopes/craft-scopes/scope-action-spec). ## Workflow file format Here's a basic example: ```yaml 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 ```yaml 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](/docs/cli/) to execute a workflow manually. ```bash 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 ```bash np service workflow exec --workflow ./deployment/workflows/create.yaml ``` - With overrides and shared parameters: ```bash 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. ```bash export NP_ACTION_CONTEXT=your_context_here ``` or ```bash 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 are some examples, but you can check our [Event payloads docs](/docs/notifications/event-payloads) for more details.
Click to view example scope context ```json { "account": { "id": 2, "nrn": "organization=1:account=2", "name": "account-name", "slug": "account-name", "organization_id": 1, "status": "active", "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 ```json { "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](/docs/agent-backed-scopes/overrides).