CI/CD Integration

Integrate Ellygent CLI into your continuous integration and deployment pipelines.

CLI Demo: Authenticate and Download Project Context

Watch a live walkthrough showing how to authenticate with the Ellygent CLI and download structured context from an existing project into a local engineering workflow.

Watch on YouTube

Overview

The Ellygent CLI is designed for automation-first workflows. Use it in CI/CD pipelines to:

Download requirements and specifications for validation
Inject engineering context into AI-assisted code generation
Verify traceability between code and requirements
Generate compliance reports and documentation
Ensure builds align with approved architecture

Authentication in CI/CD

Always use Personal Access Tokens with ELLYGENT_TOKEN in CI/CD pipelines.

Step 1: Generate a PAT

Log in to Ellygent web interface
Go to Account → Personal Access Tokens
Create a token named "CI Pipeline" or similar
Copy the token (starts with elly_pat_)

Step 2: Store PAT as Secret

Add the PAT to your CI platform's secret management:

GitHub Actions: Settings → Secrets → Actions → New repository secret
GitLab CI: Settings → CI/CD → Variables → Add variable
Jenkins: Credentials → Global → Add credentials → Secret text
CircleCI: Project Settings → Environment Variables → Add variable

GitHub Actions

Basic Workflow

name: Download Engineering Context

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  sync-context:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Install Ellygent CLI
        run: |
          git clone --depth 1 https://github.com/EEQuality/ellygent-cli.git ./ellygent-cli
          npm install --prefix ./ellygent-cli
          npm run build --prefix ./ellygent-cli
          npm install -g ./ellygent-cli

      - name: Authenticate with Ellygent
        env:
          ELLYGENT_TOKEN: ${{ secrets.ELLYGENT_TOKEN }}
        run: ellygent auth login --token $ELLYGENT_TOKEN --url https://www.ellygent.com

      - name: Download context
        run: |
          ellygent context pull \
            --project safety-system \
            --version v2.1 \
            --include-traceability

      - name: Verify context
        run: |
          ls -la .ellygent/
          cat .ellygent/metadata.json

Advanced: Matrix Strategy

Sync multiple projects or versions in parallel:

name: Multi-Project Sync

on: [push]

jobs:
  sync-matrix:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        project:
          - { id: 'safety-system', version: 'v2.1' }
          - { id: 'platform-api', version: 'main' }
          - { id: 'frontend-app', version: 'v1.0' }
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Install CLI
        run: |
          git clone --depth 1 https://github.com/EEQuality/ellygent-cli.git ./ellygent-cli
          npm install --prefix ./ellygent-cli
          npm run build --prefix ./ellygent-cli
          npm install -g ./ellygent-cli

      - name: Sync ${{ matrix.project.id }}
        env:
          ELLYGENT_TOKEN: ${{ secrets.ELLYGENT_TOKEN }}
        run: |
          ellygent auth login --token $ELLYGENT_TOKEN --url https://www.ellygent.com
          ellygent context pull \
            --project ${{ matrix.project.id }} \
            --version ${{ matrix.project.version }} \
            --workspace ./context/${{ matrix.project.id }}/

GitLab CI

Basic Pipeline

stages:
  - sync

sync-context:
  stage: sync
  image: node:18
  before_script:
    - git clone --depth 1 https://github.com/EEQuality/ellygent-cli.git ./ellygent-cli
    - npm install --prefix ./ellygent-cli
    - npm run build --prefix ./ellygent-cli
    - npm install -g ./ellygent-cli
  script:
    - ellygent auth login --token $ELLYGENT_TOKEN --url https://www.ellygent.com
    - ellygent context pull --project safety-system --version v2.1
    - ls -la .ellygent/
  variables:
    ELLYGENT_TOKEN: ${ELLYGENT_TOKEN}
  artifacts:
    paths:
      - .ellygent/
    expire_in: 1 week

Conditional Sync on Tag

sync-on-release:
  stage: sync
  image: node:18
  before_script:
    - git clone --depth 1 https://github.com/EEQuality/ellygent-cli.git ./ellygent-cli
    - npm install --prefix ./ellygent-cli
    - npm run build --prefix ./ellygent-cli
    - npm install -g ./ellygent-cli
  script:
    - ellygent auth login --token $ELLYGENT_TOKEN --url https://www.ellygent.com
    - ellygent context pull --project platform-api --version ${CI_COMMIT_TAG}
  variables:
    ELLYGENT_TOKEN: ${ELLYGENT_TOKEN}
  only:
    - tags

Jenkins

Declarative Pipeline

pipeline {
    agent any

    environment {
        ELLYGENT_TOKEN = credentials('ellygent-token')
        NODE_VERSION = '18'
    }

    stages {
        stage('Setup') {
            steps {
                sh 'git clone --depth 1 https://github.com/EEQuality/ellygent-cli.git ./ellygent-cli && npm install --prefix ./ellygent-cli && npm run build --prefix ./ellygent-cli && npm install -g ./ellygent-cli'
            }
        }

        stage('Authenticate') {
            steps {
                sh 'ellygent auth login --token $ELLYGENT_TOKEN --url https://www.ellygent.com'
            }
        }

        stage('Sync Context') {
            steps {
                sh '''
                    ellygent context pull \
                      --project safety-system \
                      --version v2.1 \
                      --include-traceability
                '''
            }
        }

        stage('Validate') {
            steps {
                sh 'cat .ellygent/metadata.json'
                sh 'find .ellygent -name "*.md" | wc -l'
            }
        }
    }

    post {
        always {
            archiveArtifacts artifacts: '.ellygent/**', fingerprint: true
        }
    }
}

CircleCI

version: 2.1

jobs:
  sync-context:
    docker:
      - image: cimg/node:18.0
    steps:
      - checkout

      - run:
          name: Install Ellygent CLI
          command: git clone --depth 1 https://github.com/EEQuality/ellygent-cli.git ./ellygent-cli && npm install --prefix ./ellygent-cli && npm run build --prefix ./ellygent-cli && npm install -g ./ellygent-cli

      - run:
          name: Authenticate
          command: ellygent auth login --token $ELLYGENT_TOKEN --url https://www.ellygent.com
          environment:
            ELLYGENT_TOKEN: $ELLYGENT_TOKEN

      - run:
          name: Download context
          command: |
            ellygent context pull \
              --project safety-system \
              --version v2.1

      - store_artifacts:
          path: .ellygent
          destination: context

workflows:
  version: 2
  build:
    jobs:
      - sync-context

Best Practices

✅ Use Personal Access Tokens

Use PAT-backed ELLYGENT_TOKEN values in CI/CD. They are revocable and designed for automation.

✅ Store Secrets Securely

Use your CI platform's secret management. Never hardcode tokens in pipeline files.

✅ Cache CLI Installation

Cache node_modules or the CLI binary to speed up builds.

✅ Use JSON Output for Parsing

Process CLI output programmatically with --format json and tools like jq.

✅ Archive Context as Artifacts

Save synced context as build artifacts for debugging and auditing.

✅ Validate Downloaded Context

Check that expected files exist and metadata is valid before proceeding with builds.

Previous: Examples Next: Troubleshooting