@evernaut/rocket-gha-agent

Thin execution agent for Rocket that runs inside GitHub Actions. Performs codebase analysis and doc ingestion on your repository, sending results back to Rocket for knowledge graph construction.

How it works

1. Rocket dispatches a GitHub Actions workflow with a session ID
2. The agent connects to Rocket, receives a single command
3. The agent executes the command (read-only filesystem operations)
4. The agent posts the result back to Rocket and exits

All intelligence stays server-side. The agent is a stateless executor that reads files and returns structured data.

Usage

This package is designed to be run via npx in a GitHub Actions workflow. You don't install it directly.

Add .github/workflows/rocket.yml to your repository:

name: Rocket Agent
on:
  workflow_dispatch:
    inputs:
      session_id:
        description: 'Rocket session ID'
        required: true
        type: string
      rocket_url:
        description: 'Rocket server URL'
        required: true
        type: string

jobs:
  agent:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Run Rocket Agent
        run: npx @evernaut/rocket-gha-agent@latest
        env:
          ROCKET_SESSION_ID: ${{ inputs.session_id }}
          ROCKET_URL: ${{ inputs.rocket_url }}

Rocket triggers this workflow automatically when you start a knowledge build.

Commands

The agent supports these commands (assigned by the Rocket server):

| Command | Description | | ------------------------ | ------------------------------------------------------------------- | | analyze-file-structure | Directory tree, file counts by extension, naming patterns | | analyze-conventions | Import style, semicolons, quotes, indentation, tooling detection | | analyze-framework | Framework, UI library, state management, router, build tool | | analyze-configs | Read and summarize config files (tsconfig, eslint, prettier, etc.) | | analyze-routes | Extract route definitions (Vue Router, React Router, Express, etc.) | | analyze-components | Extract component tree with props/events/slots | | discover-and-read-docs | Find and read documentation files (README, ADRs, API specs, etc.) | | bash | Execute a bash command (read-only), upload stdout/stderr to R2 |

Security

• Read-only: only reads files from the checked-out repository (bash commands should not modify files)
• No secrets: does not access GITHUB_TOKEN or any repository secrets
• Single endpoint: communicates only with the Rocket server that dispatched it
• Session-scoped: authenticates via a one-time session UUID
• No code execution: commands are a fixed allowlist, arguments are data not code
• CF Access bypass: non-production environments behind Cloudflare Access can pass CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET env vars via the workflow template's optional inputs. These are forwarded as service token headers so GHA runners can reach the Rocket server through Zero Trust

License

Proprietary. Copyright Evernaut.