Project Structure

Running npm create @ci-hub/integration my-integration scaffolds:

index.ts

All integration logic lives in index.ts. The file contains defineIntegration, every handler, and all helper functions.

Split only for long static data (see below).

When to split

You might need to split your code into multiple files if you have a lot of static data like GraphQL queries, predefined renditions, or predefined filters.

cihub.config.jsonc

The CLI configuration file that controls how source files, templates, and assets are discovered and bundled. Run integration-cli config --init to generate a starter file (see CLI reference for your package manager). See the CLI reference for all available fields and defaults.

config.json

Integration-specific configuration. Keys are accessed via config.get('integrationName.key').

{
  "serverBaseUrl": "http://localhost:8080",
  "IntegrationName": {
    "contact": {
      "text": "Support description",
      "url": { "link": "https://your-platform.example.com/help", "email": "support@example.com" }
    },
    "authEndpoint": "/api/oauth/authorize",
    "tokenEndpoint": "/api/oauth/accesstoken",
    "clientId": "your-client-id",
    "maxQuerySize": 100
  }
}

import { config } from '@ci-hub/integration-sdk'

const apiUrl = config.get('IntegrationName.apiUrl')
const limit = config.has('IntegrationName.uploadLimitMB') 
  ? config.get<number>('IntegrationName.uploadLimitMB')   
  : 500

Logo and glyph

Images are inlined as base64 data URLs. Place logo.png (600×134) and glyph.png (80×80) next to the index.ts file.

import { fs, path } from '@ci-hub/integration-sdk'

const imageBase64 = (name: string) =>
  `data:image/png;base64,${Buffer.from(
    fs.readFileSync(path.join(import.meta.dirname, name))
  ).toString('base64')}`

const logo  = { data: imageBase64('logo.png'),  width: 600, height: 134, backgroundColor: '#FFFFFF' }
const glyph = { data: imageBase64('glyph.png'), width: 80,  height: 80,  backgroundColor: '#FFFFFF' }