GitLab CI

The official Constellation Index Component installs the latest Constellation CLI and indexes your repository automatically. Only structural metadata is extracted, source code never leaves your pipeline environment.

Source: gitlab.com/shiftinbits/constellation-gitlab

Quick Start

include:
  - component: gitlab.com/shiftinbits/constellation-gitlab/constellation-index@1
    inputs:
      access_key: $CONSTELLATION_ACCESS_KEY

stages:
  - build

Setup

1. Get an Access Key

Sign up at constellationdev.io to obtain your API access key.

2. Add CI/CD Variable

1. Go to your project Settings > CI/CD > Variables
2. Click Add variable
3. Key: CONSTELLATION_ACCESS_KEY
4. Value: Your Constellation API access key
5. Check Mask variable to hide in job logs
6. Optionally check Protect variable for protected branches only
7. Click Add variable

3. Add Pipeline Configuration

Create or update .gitlab-ci.yml with one of the examples below.

Pipeline Examples

Index on push to default branch

The recommended default — re-index whenever code lands on your default branch:

include:
  - component: gitlab.com/shiftinbits/constellation-gitlab/constellation-index@1
    inputs:
      access_key: $CONSTELLATION_ACCESS_KEY

stages:
  - build

constellation-index:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: never
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Scheduled indexing

Trigger a full re-index on a schedule or via manual pipeline runs:

include:
  - component: gitlab.com/shiftinbits/constellation-gitlab/constellation-index@1
    inputs:
      access_key: $CONSTELLATION_ACCESS_KEY
      skip_diff_check: "true"

stages:
  - build

constellation-index:
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
    - if: $CI_PIPELINE_SOURCE == "web"  # Manual trigger

Using outputs

The component exports variables via dotenv artifacts that can be used in downstream jobs:

include:
  - component: gitlab.com/shiftinbits/constellation-gitlab/constellation-index@1
    inputs:
      access_key: $CONSTELLATION_ACCESS_KEY

stages:
  - build
  - notify

check-result:
  stage: notify
  needs: [constellation-index]
  script:
    - echo "Indexed: $INDEXED"
    - echo "Summary: $SUMMARY"

How It Works

The component performs three main steps:

1. Install tooling — Installs jq (if needed), the Constellation CLI, and language servers for index enrichment
2. Diff detection — Checks which files changed and compares them against the languages and exclude configuration in your constellation.json. If none of the changed files match a configured file extension (or all matching files are excluded), indexing is skipped entirely. This reduces pipeline minutes on commits that only change non-code files like documentation or images.
3. Index — Runs const index to extract structural metadata and upload it to the Constellation API

Indexing always runs when:

• This is the first push to a branch (no baseline to diff against)
• The trigger is schedule or web (no push event context)
• The git diff fails — falls back to indexing with a warning
• skip_diff_check is set to "true"

A constellation.json file is required in the repository root. The job will fail if it is missing.

Index Enrichment

The component automatically installs language servers (typescript-language-server, typescript, and pyright) so that const index can enrich your index with additional type information, cross-references, and call hierarchy data.

Index enrichment runs automatically for any language that has a compatible language server available. The CLI auto-detects installed servers from its built-in registry — no configuration in constellation.json is required. Enrichment never blocks the core indexing pipeline; if a language server is unavailable, enrichment is silently skipped for that language.

To disable enrichment for a specific language or globally, see the enrichment configuration options.

Reference

Inputs

Input	Required	Default	Description
access_key	Yes	—	Constellation API access key. Store as a CI/CD variable.
error_reporting	No	true	Enable error reporting to Constellation in the event of indexing failures.
skip_diff_check	No	false	Skip the diff check and always run indexing. Useful for scheduled runs.
stage	No	build	Pipeline stage for the indexing job.
image	No	node:24	Docker image for the job (must include Node.js 24+).

Outputs

Variables exported via dotenv artifacts:

Output	Description
INDEXED	true if indexing completed successfully, false otherwise
SUMMARY	Human-readable summary of the indexing operation

Requirements

• GitLab: 17.0+ (CI/CD components support)
• Runner: Any runner with Docker executor
• Image: Node.js 24+ (default: node:24)
• jq: Auto-installed if not present in the image (used for diff detection)
• Language servers: Automatically installed (typescript-language-server, typescript, pyright) for index enrichment

Troubleshooting

Authentication Errors

Error: Authentication failed

Verify your CONSTELLATION_ACCESS_KEY CI/CD variable is correctly set and has not expired. You can regenerate keys in the Constellation web UI.

Network Errors

Error: Connection refused

The Constellation API may be temporarily unavailable. The job will fail and can be retried. If the issue persists, check status.constellationdev.io.

Parse Errors

Error: Failed to parse file

Some files may contain syntax not yet supported by Constellation. These files are skipped, and indexing continues for supported files.

Security

• No source transmission — Only structural metadata is transmitted, never source code
• Masked variables — Access keys should be masked in CI/CD variable settings
• Minimal permissions — Component only needs read access to repository files
• Automatic updates — Always uses the latest CLI version with the newest security patches