#CI/CD Automation

Zephyr requires authenticated CI/CD pipelines to publish updates. Use CI tokens for deployment authentication.

#Creating a CI Token

First, create a CI token from Organization Settings > CI tokens. This token will be used to authenticate your CI/CD pipeline with Zephyr. See CI Tokens for how tokens are exchanged, which CI providers are supported, and how deployments are attributed.

#GitHub Actions

#Adding the GitHub Secret

Add your Zephyr token as a repository secret:

1. Navigate to your GitHub repository
2. Go to Settings → Secrets and variables → Actions
3. Click New repository secret
4. Set:
   • Name: ZEPHYR_CI_TOKEN
   • Secret: Your Zephyr CI token

#Using in Workflow

The secret must be assigned to the ZE_CI_TOKEN environment variable:

name: Deploy with Zephyr
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      ZE_CI_TOKEN: ${{ secrets.ZEPHYR_CI_TOKEN }}
      ZE_FAIL_BUILD: true

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

      - name: Install dependencies
        run: npm ci

      - name: Build and deploy
        run: npm run build

#GitLab CI/CD

#Adding the GitLab Variable

Add your Zephyr token as a CI/CD variable:

1. Navigate to your GitLab project
2. Go to Settings → CI/CD
3. Expand the Variables section
4. Click Add variable
5. Set:
   • Key: ZE_CI_TOKEN
   • Value: Your Zephyr CI token
   • Type: Variable
   • Environment scope: All (or specify environments)
   • Protect variable: ✓ (recommended)
   • Mask variable: ✓ (recommended)

#Using in Pipeline

stages:
  - install
  - build
  - deploy

variables:
  npm_config_cache: '$CI_PROJECT_DIR/.npm'

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - .npm/
    - node_modules/

install:
  stage: install
  script:
    - npm ci --cache .npm --prefer-offline
  artifacts:
    paths:
      - node_modules/
    expire_in: 1 hour

build:
  stage: build
  script:
    - npm run build
  variables:
    ZE_CI_TOKEN: $ZE_CI_TOKEN
    ZE_FAIL_BUILD: true
  artifacts:
    paths:
      - dist/
    expire_in: 1 day

deploy:
  stage: deploy
  script:
    - npm run deploy
  only:
    - main
  environment:
    name: production
  variables:
    ZE_CI_TOKEN: $ZE_CI_TOKEN
    ZE_FAIL_BUILD: true

#Fail the build on Zephyr errors

By default, Zephyr logs plugin and deployment errors without failing your application build. In CI/CD, set ZE_FAIL_BUILD to true so Zephyr rethrows these errors and the build exits with a failure status:

ZE_FAIL_BUILD=true npm run build

Only the value true enables this behavior. If ZE_FAIL_BUILD is unset or set to any other value, Zephyr logs the error and allows the build to continue.

#Plugin Behavior

When the Zephyr plugin detects the ZE_CI_TOKEN environment variable, it will:

1. Use the token for automatic authentication
2. Skip the interactive login step
3. Display this message in the console:

 ZEPHYR   Token found in environment. Using CI token for authentication

#Troubleshooting

#Token not found

• Ensure the variable name is exactly ZE_CI_TOKEN
• Verify the variable is available in the job environment
• Check that the token hasn't expired

#GitHub Actions Issues

• Make sure the secret is added to the correct repository
• Verify the secret name matches what's referenced in the workflow

#GitLab CI/CD Issues

• If using protected variables, ensure your pipeline runs on protected branches
• Masked variables won't appear in logs (recommended for security)
• Check variable scope matches your branch/environment