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 indexing on a schedule or via manual pipeline runs:

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

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.
stage	No	build	Pipeline stage for the indexing job.
image	No	node:20-slim	Docker image for the job (must include Node.js 20+).

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 20+ (default: node:20-slim)

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