CI/CD & Deployment

Deploy connectors with GitHub Actions and environment-based branch routing

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.

---

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)

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

Multi-Environment

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:

1. Configure the Integration

   Enable your custom connector in the Auth Configs page.

   Auth Configuration Guide
2. Link an Account

   Create a linked account using StackOne Connect or the API.

3. Test in Playground

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

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

AI Builder

AI-powered connector generation