Push & Pull Configuration

Managing Serval workflows locally with the CLI

Push & Pull Configuration

The Serval CLI enables you to manage your team’s workflows locally, allowing you to use your preferred development tools and integrate with version control systems like Git.

Authentication

Before you can pull or push workflows, you need to authenticate with Serval:

serval login

This will initiate a device authentication flow:

1. The CLI will display a device code and URL
2. Visit the URL in your browser (e.g., https://app.serval.com/auth/device?code=XXXX-1234)
3. Confirm the authentication in your browser
4. The CLI will automatically detect successful authentication

Example output:

🔐 Device Authentication Required
================================
Please visit the Serval web app at https://app.serval.com/auth/device?code=XXXX-1234
Waiting for authorization...
✅ Successfully authenticated!

To check your authentication status:

serval status

To log out:

serval logout

Finding Your Team Prefix

To work with a team’s workflows, you need its prefix. You can find team prefixes by:

1. Visiting admin settings in Serval
2. Navigating to the Teams section
3. Looking for the team prefix (e.g., EXA, DEV, OPS)

The prefix is also included in the URL when you visit a team’s workflows or tickets in the web app.

Pulling Workflows

To download a team’s workflows and configuration:

serval pull <team-prefix>

For example:

serval pull EXA

This creates a local directory structure:

EXA/                         # Team directory
├── team.yaml               # Team metadata
└── workflows/              # All workflows for this team
    ├── hello-world/
    │   ├── index.ts       # Workflow implementation
    │   └── workflow.yaml  # Workflow metadata
    └── onboard-employee/
        ├── index.ts
        └── workflow.yaml

Directory Structure

• Team Directory: Named after the team prefix (e.g., EXA/)
• team.yaml: Contains team-level metadata and configuration
• workflows/: Contains all workflows for the team
• Workflow Folders: Each workflow has its own directory with:
  • index.ts: The TypeScript implementation of the workflow
  • workflow.yaml: Workflow metadata and configuration

Workflow Metadata (workflow.yaml)

Each workflow includes a workflow.yaml file with the following structure:

name: Hello World
description: This is the workflow description.
slug: hello-world
deployed: true
approval_procedure:
    steps:
        - step_type: groups
          group_ids:
            - 01959d51-dcfg-7dfc-9e9b-742237d518c7
version: 1

Key fields:

• name: Display name of the workflow
• description: Detailed description of what the workflow does
• slug: URL-friendly identifier (must match the folder name)
• deployed: Whether the workflow is active in Serval
• approval_procedure: Defines who can approve workflow runs
• version: Workflow version number

Editing Workflows

Once pulled, you can edit workflows using any text editor or IDE:

1. Modify workflow code: Edit the index.ts file to change workflow behavior
2. Update metadata: Modify workflow.yaml to change description, approval procedures, etc.
3. Test locally: Use your standard TypeScript development tools
4. Version control: Commit changes to Git or your preferred VCS

Pushing Changes

After making local changes, push them back to Serval:

serval push <team-prefix>

For example:

serval push EXA

The CLI will:

1. Validate your local changes
2. Compare with the remote state
3. Upload modified workflows
4. Update workflow versions
5. Deploy changes if deployed: true

Push Behavior

• New workflows: Created if they don’t exist in Serval
• Modified workflows: Updated with your changes
• Deleted workflows: Not automatically deleted (manual deletion required in UI)
• Validation: The CLI validates YAML syntax and basic structure before pushing

Working with Multiple Teams

You can manage workflows for multiple teams:

# Pull workflows from different teams
serval pull EXA
serval pull DEV
serval pull OPS

# Your directory structure will be:
# EXA/
#   └── workflows/
# DEV/
#   └── workflows/
# OPS/
#   └── workflows/

Best Practices

Version Control

1. Initialize Git in your workflow directory:

   git init
   cd EXA
   git add .
   git commit -m "Initial workflow commit"
   

2. Use branches for workflow changes:

   git checkout -b update-onboarding-workflow
   # Make changes
   git commit -m "Add manager approval to onboarding"
   # Review and merge in your VCS
   # After merging, push to Serval
   serval push EXA
   

Development Workflow

1. Pull latest: Always pull before making changes

   serval pull EXA
   

2. Make changes: Edit workflows locally

3. Test: Validate your TypeScript code

4. Commit: Save changes to version control

5. Push: Deploy to Serval

   serval push EXA