GitHub Actions

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

Source: github.com/ShiftinBits/constellation-github

Quick Start

- uses: ShiftinBits/constellation-github@v1
  with:
    access-key: ${{ secrets.CONSTELLATION_ACCESS_KEY }}

Setup

1. Get an Access Key

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

2. Add Repository Secret

1. Go to your repository Settings > Secrets and variables > Actions
2. Click New repository secret
3. Name: CONSTELLATION_ACCESS_KEY
4. Value: Your Constellation API access key
5. Click Add secret

3. Add Workflow

Create .github/workflows/constellation.yml with one of the examples below.

Workflow Examples

Index on push to main

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

name: Constellation Index

on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  index:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: ShiftinBits/constellation-github@v1
        with:
          access-key: ${{ secrets.CONSTELLATION_ACCESS_KEY }}

See a live implementation example in the Constellation CLI repository.

Scheduled indexing

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

name: Constellation Index (Scheduled)

on:
  schedule:
    - cron: '0 2 * * *'
  workflow_dispatch:

permissions:
  contents: read

jobs:
  index:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: ShiftinBits/constellation-github@v1
        with:
          access-key: ${{ secrets.CONSTELLATION_ACCESS_KEY }}
          skip-diff-check: "true"

Using outputs

The action provides outputs you can use in subsequent steps:

- uses: ShiftinBits/constellation-github@v1
  id: constellation
  with:
    access-key: ${{ secrets.CONSTELLATION_ACCESS_KEY }}

- name: Check Result
  run: |
    echo "Indexed: ${{ steps.constellation.outputs.indexed }}"
    echo "Summary: ${{ steps.constellation.outputs.summary }}"

How It Works

The action performs three main steps:

1. Install tooling — Sets up Node.js 24, installs the Constellation CLI, and installs 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 CI 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 workflow_dispatch (no push event context)
• The git diff fails (e.g., shallow clone) — 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 action will fail if it is missing.

Index Enrichment

The action 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 repository secret.
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.

Outputs

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

Permissions

Permission	Level	Reason
contents	read	Read repository files for metadata extraction

Requirements

• Node.js: 24.x (automatically set up by the action)
• Runner: Ubuntu, macOS, or Windows
• jq: Pre-installed on all GitHub-hosted runners (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 secret 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 action retries automatically. 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
• Encrypted secrets — Access keys are stored encrypted in GitHub Secrets
• Minimal permissions — Only contents: read permission required
• Automatic updates — Always uses the latest CLI version with the newest security patches