GitHub CI/CD - Stackone

Publishing from a Git pipeline instead of your own machine means every change is validated on the pull request, and merging is what pushes the connector to a project. It also gives you one API key per environment rather than one on each developer’s laptop.

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

The pipeline is yours to shape:

Single project: push to one project from any branch
Multi-environment: route branches to separate projects, such as develop to dev and main to production
Custom: your own branch strategy and approval gates

Repository structure

Organize the repository however suits your team. What matters is that the connector directories keep the layout described in File Structure, so validate and push can be pointed at a single parent directory:

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

Add your API key as a secret

In the repository, go to Settings → Secrets and variables → Actions and add the API key for the project you’re publishing to:

Secret	Description
`STACKONE_API_KEY`	API key for your StackOne project

The key needs the connectors:write scope to push. See API Keys for generating one.

Create the workflow file

Create .github/workflows/deploy.yml. Both examples validate on pull requests and publish only on a push to a release branch:

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: Check agent skills are in sync
        run: stackone agent sync --check

      - 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, and production projects, add one secret per project:

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/
      - run: stackone agent sync --check

  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 }}

stackone agent sync --check compares the .claude/skills/ and CLAUDE.md guide committed in the repository against the ones bundled with the installed CLI, and exits non-zero if they differ. It needs no credentials.

Because the workflow installs the latest CLI, a new CLI release that ships updated skills will fail this step until someone runs stackone agent sync and commits the result. Pin the CLI version in the workflow if you’d rather choose when that happens.

Test after deploying

A published connector needs a linked account before you can call anything against it:

Enable the connector

Turn your custom connector on in the project’s connector profiles, and enable the actions you want exposed.

Managing Connectors

Connector profiles, authentication, and scoping.

Link an account

Create a linked account through the Hub or the API.

Run it

Select the account in the Playground and try the actions in natural language, or run one directly:

stackone run \
  --connector connectors/[provider]/[provider].connector.s1.yaml \
  --account-id [account-id] \
  --profile [profile-label] \
  --action-id [action-id]

The profile’s API key needs the credentials:read scope to use a linked account’s stored credentials.

Iterate

Push updates as you refine the connector. Existing linked accounts are unaffected until you move them, which is covered in Connector Versioning.

Common errors

Validation fails in CI but passes locally

Check YAML indentation, which must be 2 spaces rather than tabs
Partial files start with -, not actions:
Every $ref matches an actual file name, which matters on case-sensitive CI runners even when it works on macOS
Run stackone validate connectors/ locally against the same parent directory the workflow uses

Push fails with an authentication error

The secret name in the workflow matches the one in repository settings
The API key carries the connectors:write scope
The key belongs to the project you intended to publish to, not another environment

Workflow does not trigger

The file sits in .github/workflows/
Branch names in on.push.branches match your actual branches
The paths filter covers the files you changed. Editing only a workflow or README will not match connectors/**

Next steps

Build Workflow

The build and debug loop that comes before publishing.

Connector Versioning

Release new versions without breaking existing linked accounts.

StackOne CLI

Full reference for validate, run, and push.

​Repository structure

​Add your API key as a secret

​Create the workflow file

​Test after deploying

Managing Connectors

​Common errors

​Next steps

Build Workflow

Connector Versioning

StackOne CLI

Repository structure

Add your API key as a secret

Create the workflow file

Test after deploying

Common errors

Next steps