Ingest a prepared constellation
You have StellarView running. This is the next step: pull in a build that has already been planned for you, against your own repositories, and see it before you run anything.
A constellation is one build spanning several repositories. A prepared one has already been decomposed into phases and work units. The planning is done, and what arrives on your machine is the plan, not a blank page.
Nothing here writes to your repositories. Importing reads; running is a separate, later decision that you make.
Before you start
| StellarView running | http://localhost:3456 — see Install |
| The epic number | e.g. #601, in your own GitHub |
| A GitHub token | on the account that can read the repositories in the epic |
The epic lives as issues in your GitHub organisation, not ours. That is the whole transport: we publish the plan into your repository, and your StellarView reads it from there. Nothing is copied between machines, and no credential of ours is involved.
1 · Create the galaxy
A galaxy is StellarView's view of one repository: its files, its layers, its history. A constellation spanning three repositories needs three.
In the interface: Galaxies → New, give it the repository URL, and let the analysis finish. It reads the code; it does not modify it.
Do this for each repository the epic touches. The epic names them.
2 · Give it a token
Per galaxy, in that galaxy's settings, add a GitHub token with read access to the repository. StellarView resolves credentials per galaxy at the moment it uses them, there is no global token, and one galaxy cannot reach another's.
If you intend to let it open pull requests later, the token needs write. It does not need write to import.
3 · Import the epic
Epics → Import from GitHub, enter the epic issue number, and choose the galaxy that owns it.
StellarView reads the epic and its child issues and reconstructs the phases and work units as a staged epic. Staged means visible and editable, not running.
4 · Read it before you run it
This is the step worth taking slowly, because a prepared plan is still a proposal.
Open the epic and look for:
- Phases in an order you would defend. Sequencing is a judgement about your system; disagree with it freely and change it.
- Work units that say extend or wire rather than create, wherever the capability already exists in your code. If something proposes building what you know you already have, that is a defect in the plan and worth saying so before it runs.
- Gaps. Questions the plan could not answer for itself. They are answerable in place, and answering them is the highest-value thing you can do here.
Editing a staged epic changes what will be built. It is meant to be edited.
What happens if the plan is wrong about your code
Say so, and change it. A prepared constellation is reconciled against your repository at the time it is planned, and repositories move. A work unit written against a file that has since been refactored is wrong in a way only you can see.
The failure worth catching early is a work unit that proposes creating something already present. That produces a second implementation beside a working one, and it is quiet. Nothing about the plan is binding, and finding this at review costs minutes where finding it after a run costs a phase.
Then, when you are ready
Running is a separate decision, made from the epic once you are satisfied with it. What that involves is covered separately: branches, pull requests, and what StellarView will and will not do to your repository. That is the point at which something changes on your side, so it deserves its own reading.
If something does not work
| What you see | What it usually means |
|---|---|
| Import returns nothing | the epic number is right but the galaxy is wrong — they must match |
| "Not found" on a private repo | the token is missing, or lacks read on that repository |
| Analysis never finishes | a large repository on a first read; it is doing work, give it time |
| Work units reference unfamiliar paths | the plan was made against an older commit — worth flagging |
The state is all on your disk, under galaxies/. Deleting a galaxy and re-creating it costs only the analysis time, and it is a reasonable thing to do when something looks wrong.