CI/CD & Deployment

Set up automated validation and deployment for your custom connectors using GitHub Actions.

Overview

The deployment pipeline is fully customizable. You can:

Single project: Push directly to one project on any branch
Multi-environment: Route branches to different projects (dev → staging → prod)
Custom workflows: Define your own branch strategy and approval gates

The example below shows a multi-environment setup, but adapt it to your needs.

CI/CD workflow: Edit YAML → Validate → Push → GitHub Actions → StackOne Projects (dev/staging/prod)

Repository Structure

Organize your connectors however works for your team. Example:

my-connectors/
├── .github/
│   └── workflows/
│       └── deploy.yml              # CI/CD pipeline
├── connectors/
│   └── {provider}/
│       ├── {provider}.connector.s1.yaml
│       └── {provider}.{resource}.s1.partial.yaml
└── README.md

The connectors-template provides a pre-configured Node.js project with git hooks and AI agent instructions if you prefer a starting point.

GitHub Actions Workflow

Step 1: Add Secrets

Go to Settings → Secrets and variables → Actions and add your API key:

Secret	Description
`STACKONE_API_KEY`	API key for your StackOne project

Step 2: Create Workflow File

Create .github/workflows/deploy.yml:

Simple (Single Project)
Multi-Environment

name: Validate and Deploy Connectors

on:
  push:
    branches: [main]
    paths:
      - 'connectors/**'
  pull_request:
    branches: [main]
    paths:
      - 'connectors/**'

jobs:
  validate-and-deploy:
    name: Validate and Deploy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install StackOne CLI
        run: npm install -g @stackone/cli

      - name: Validate connectors
        run: stackone validate connectors/

      - name: Deploy
        if: github.event_name == 'push'
        env:
          STACKONE_API_KEY: ${{ secrets.STACKONE_API_KEY }}
        run: stackone push connectors/ --api-key $STACKONE_API_KEY

For separate dev/staging/prod projects, add multiple secrets:

Secret	Description
`STACKONE_API_KEY_DEV`	Development project
`STACKONE_API_KEY_STAGING`	Staging project
`STACKONE_API_KEY_PROD`	Production project

name: Validate and Deploy Connectors

on:
  push:
    branches: [develop, staging, main]
    paths:
      - 'connectors/**'
  pull_request:
    branches: [develop, staging, main]
    paths:
      - 'connectors/**'

jobs:
  validate:
    name: Validate Connectors
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @stackone/cli
      - run: stackone validate connectors/

  deploy-dev:
    needs: validate
    if: github.ref == 'refs/heads/develop' && github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @stackone/cli
      - run: stackone push connectors/ --api-key ${{ secrets.STACKONE_API_KEY_DEV }}

  deploy-staging:
    needs: validate
    if: github.ref == 'refs/heads/staging' && github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @stackone/cli
      - run: stackone push connectors/ --api-key ${{ secrets.STACKONE_API_KEY_STAGING }}

  deploy-prod:
    needs: validate
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest
    environment: production  # Optional: require manual approval
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @stackone/cli
      - run: stackone push connectors/ --api-key ${{ secrets.STACKONE_API_KEY_PROD }}

Git Hooks (Optional)

If using the connectors-template, it includes git hooks:

Hook	Purpose
Pre-commit	Runs linting before each commit
Post-merge	Auto-updates dependencies after pulling

# Reinstall hooks if needed
npm run setup:hooks

Local Development

Configure Profiles (Optional)

Save API keys for quick access:

stackone config set --profile myproject --api-key v1.eu1.xxxxx

Development Workflow

# Edit connector
vim connectors/provider/provider.connector.s1.yaml

# Validate (with watch mode)
stackone validate connectors/provider/ --watch

# Test locally
stackone run \
  --connector connectors/provider/provider.connector.s1.yaml \
  --account account.json \
  --credentials credentials.json \
  --action-id list_employees

# Push manually (or let CI handle it)
stackone push connectors/provider/ --profile myproject

Testing After Deployment

Before testing in the Playground, you need a linked account:

Configure the Integration

Enable your custom connector in the Connector Profiles page.

Connector Profiles Guide

Link an Account

Create a linked account using StackOne Connect or the API.

Test in Playground

Go to app.stackone.com/playground, select your linked account, and test actions.

Iterate

Refine your connector based on test results, push updates, and repeat. Each deployment is additive, so you can continuously improve without breaking existing functionality.

Alternative: Test via CLI You can also test directly using the CLI with an account ID:

stackone run \
  --connector connectors/provider/provider.connector.s1.yaml \
  --account-id your_account_id \
  --profile myproject \
  --action-id list_employees

Your profile must have an API key with the appropriate credentials scope to access the linked account.

Troubleshooting

Validation fails in CI

Check YAML indentation (2 spaces, not tabs)
Ensure partial files start with - not actions:
Verify all $ref references match file names
Run validation locally first

Push fails with authentication error

Verify API key secret is set correctly
Check the key has permissions for the target project
Ensure secret names match workflow file

Workflow not triggering

Verify workflow file is in .github/workflows/
Check branch names match triggers
Ensure paths filter includes changed files

Next Steps

CLI Reference

All CLI commands

StackOne Agent

AI-powered connector generation

Quickstart

Connect Tools

Dashboard

Build Connectors

CI/CD & Deployment

Overview

Repository Structure

GitHub Actions Workflow

Step 1: Add Secrets

Step 2: Create Workflow File

Git Hooks (Optional)

Local Development

Configure Profiles (Optional)

Development Workflow

Testing After Deployment

Connector Profiles Guide

Troubleshooting

Next Steps

CLI Reference

StackOne Agent

​Overview

​Repository Structure

​GitHub Actions Workflow

​Step 1: Add Secrets

​Step 2: Create Workflow File

​Git Hooks (Optional)

​Local Development

​Configure Profiles (Optional)

​Development Workflow

​Testing After Deployment

Connector Profiles Guide

​Troubleshooting

​Next Steps

CLI Reference

StackOne Agent

Overview

Repository Structure

GitHub Actions Workflow

Step 1: Add Secrets

Step 2: Create Workflow File

Git Hooks (Optional)

Local Development

Configure Profiles (Optional)

Development Workflow

Testing After Deployment

Troubleshooting

Next Steps