> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Frame>
  <img src="https://mintcdn.com/stackone-60/EwDvhPIppDul_dNC/images/guides/cicd-workflow.svg?fit=max&auto=format&n=EwDvhPIppDul_dNC&q=85&s=70177ad51638fa521448cf4f053f27ab" alt="CI/CD workflow: Edit YAML → Validate → Push → GitHub Actions → StackOne Projects (dev/staging/prod)" width="720" height="140" data-path="images/guides/cicd-workflow.svg" />
</Frame>

***

## 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
```

<Tip>
  The [connectors-template](https://github.com/StackOneHQ/connectors-template/) provides a pre-configured Node.js project with git hooks and AI agent instructions if you prefer a starting point.
</Tip>

***

## 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`:

<Tabs>
  <Tab title="Simple (Single Project)">
    ```yaml theme={null}
    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
    ```
  </Tab>

  <Tab title="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  |

    ```yaml theme={null}
    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 }}
    ```
  </Tab>
</Tabs>

***

## Git Hooks (Optional)

If using the [connectors-template](https://github.com/StackOneHQ/connectors-template/), it includes git hooks:

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

```bash theme={null}
# Reinstall hooks if needed
npm run setup:hooks
```

***

## Local Development

### Configure Profiles (Optional)

Save API keys for quick access:

```bash theme={null}
stackone config set --profile myproject --api-key v1.eu1.xxxxx
```

### Development Workflow

```bash theme={null}
# 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:

<Steps>
  <Step title="Configure the Integration">
    Enable your custom connector in the [Connector Profiles](https://app.stackone.com/connector_profiles) page.

    <Card title="Connector Profiles Guide" icon="gear" href="/guides/connector-profiles" />
  </Step>

  <Step title="Link an Account">
    Create a linked account using StackOne Connect or the API.
  </Step>

  <Step title="Test in Playground">
    Go to [app.stackone.com/playground](https://app.stackone.com/playground), select your linked account, and test actions.
  </Step>

  <Step title="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.
  </Step>
</Steps>

**Alternative: Test via CLI**

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

```bash theme={null}
stackone run \
  --connector connectors/provider/provider.connector.s1.yaml \
  --account-id your_account_id \
  --profile myproject \
  --action-id list_employees
```

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

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Workflow not triggering">
    * Verify workflow file is in `.github/workflows/`
    * Check branch names match triggers
    * Ensure `paths` filter includes changed files
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/guides/connector-engine/cli-reference">
    All CLI commands
  </Card>

  <Card title="StackOne Agent" icon="robot" href="/guides/connector-engine/stackone-agent">
    AI-powered connector generation
  </Card>
</CardGroup>