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 branchMulti-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_KEYAPI 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_DEVDevelopment project STACKONE_API_KEY_STAGINGStaging project STACKONE_API_KEY_PRODProduction 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 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
Link an Account
Create a linked account using StackOne Connect or the API.
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
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
Verify workflow file is in .github/workflows/
Check branch names match triggers
Ensure paths filter includes changed files
Next Steps 
MCP
A2A