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.

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

Reference

Inputs

Input	Required	Description
access-key	Yes	Constellation API access key. Store as a repository secret.

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

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