Onboarding guide

Everything you need to go from zero to your first pull request in the eigenoid org.

Prerequisites

Install the following tools before cloning any repository. Version numbers are minimums based on what repos actually use.

Tool	Version	Purpose
Node.js	>= 22	JavaScript/TypeScript repos (apps, docs, platform workers)
npm	>= 10	Ships with Node 22+. Used for dependency management in JS repos
Go	>= 1.26	Backend services (svc-* repos)
Python	>= 3.11	Eigenoid core framework and distribution packages
Terraform	>= 1.14	Infrastructure as Code (iac-* repos)
gcloud CLI	Latest	GCP authentication and resource management
GitHub CLI (gh)	Latest	Repository management, PR workflows, API queries
Git	>= 2.40	Version control with GPG signing support

Verify your setup:

node --version && npm --version
go version
python3 --version
terraform --version
gcloud --version
gh --version
git --version

bash

Repository access

Eigenoid is a private GitHub organization. All repositories are internal.

1. Get invited. Ask an existing org member to add you to the eigenoid GitHub organization.
2. Authenticate the GitHub CLI. Run gh auth login and follow the prompts. Choose HTTPS as the protocol.
3. Clone a repo. All repos follow a naming convention with category prefixes (app-, svc-, iac-, docs-, platform-).

gh repo clone eigenoid/<repo-name>

bash

To see all available repositories:

gh repo list eigenoid --limit 50

bash

Development setup

Each repository category has its own setup pattern. After cloning, run the setup commands for that repo type.

JavaScript / TypeScript (app-*, docs-*, platform-api-gateway)

npm install
npm run build
npm run typecheck    # if available
npm run dev          # dev server with HMR

bash

Most JS repos pin the Node version in .nvmrc. If you use nvm, run nvm use before installing.

Go (svc-*)

go mod download
go build ./...
go test ./...

bash

Python (eigenoid, eigenoid-sample)

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

bash

For packages distributed via Artifact Registry, you also need the keyring helper:

pip install keyrings.google-artifactregistry-auth
gcloud auth application-default login

bash

Terraform (iac-*)

terraform init
terraform validate

bash

Terraform repos use the producer/consumer model. You will not run terraform plan or apply locally in most cases -- CI handles that through the Terraflow orchestrator.

Coding conventions

These conventions apply across every repository in the org.

Language

All code, comments, commit messages, PR titles, PR descriptions, and documentation are written in English. No exceptions.

Commits

We use Conventional Commits. Every commit message follows this format:

<type>(<optional scope>): <description>

Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.

Examples:

feat(auth): add magic link login flow
fix: resolve race condition in session refresh
docs(adr): add ADR-0014 for API gateway routing
ci: pin checkout action to latest SHA

Branching

Use descriptive kebab-case branch names:

feat/token-vending-machine
fix/settings-sync-race
docs/onboarding-guide

Product and service repos (app-*, svc-*) use a three-branch model: dev -> qa -> main. Infrastructure and other repos work directly on main.

Merge strategy

All repositories use squash merge only. Your branch history gets condensed into a single clean commit on main. Write a clear PR title -- it becomes the commit message.

No emojis

Do not use emojis anywhere in committed content: not in docs, code, commits, or PR descriptions.

Your first contribution

Here is the typical workflow from branch to merged PR.

1. Create a branch

git checkout -b feat/my-first-change

bash

2. Make your changes

Edit the relevant files. Follow the conventions above and any repo-specific rules in that repo's AGENTS.md or CONTRIBUTING.md.

3. Run checks locally

Before pushing, verify your changes pass the repo's checks:

# For JS/TS repos
npm run typecheck && npm run build

# For Go repos
go test ./... && go vet ./...

# For Python repos
pytest

# For Terraform repos
terraform validate

bash

4. Commit and push

git add -A
git commit -m "feat: describe what you changed"
git push -u origin feat/my-first-change

bash

Git commits are GPG-signed (see Key tools below). If the commit hangs, it is waiting for you to authorize the GPG signature in 1Password.

5. Create a pull request

gh pr create --fill

bash

Or use gh pr create interactively to set the title, body, and reviewers.

6. What CI does

When you open a PR, GitHub Actions will automatically:

• Typecheck and build the project (for JS/TS repos).
• Run tests (for Go and Python repos).
• Generate a preview deployment on Cloudflare Pages (for documentation sites).
• Run Terraform plan and post results as a PR comment (for iac-* repos via Terraflow).

Fix any CI failures before requesting review. The preview URL appears as a comment or check on your PR.

Key tools

GitHub CLI (gh)

The primary interface for working with GitHub from the terminal. Use it for cloning, PRs, issue management, and API queries.

gh pr list                          # list open PRs
gh pr view 42                       # view PR details
gh issue list                       # list open issues
gh api repos/eigenoid/<repo>/releases/latest   # check latest release

bash

Git with GPG signing

All commits are signed using GPG keys managed through 1Password. This is configured at the Git level -- you do not need to do anything special per commit. If a commit operation seems to hang, open 1Password and authorize the signing request.

Verify signing is configured:

git config --global commit.gpgsign    # should be true
git config --global gpg.program       # should point to 1Password's agent

bash

gcloud CLI

Used to interact with GCP resources. The org runs three GCP projects (eigenoid-dev, eigenoid-qa, eigenoid-prd) per ADR-0009.

gcloud auth login                         # browser-based auth
gcloud config set project eigenoid-dev    # set default project
gcloud run services list                  # list Cloud Run services

bash

In CI, authentication happens through Workload Identity Federation (no stored secrets). You only need gcloud for local debugging and exploration.

Troubleshooting

Problem	Cause	Fix
git commit hangs for 10+ seconds	GPG signing waiting for 1Password approval	Open 1Password and authorize the signing request
terraform init fails with backend error	State bucket not bootstrapped	Run make bootstrap-plan ENV=dev && make bootstrap-apply ENV=dev
npm install fails with permission errors	Wrong Node version	Run nvm use to load the version from .nvmrc
gcloud auth errors in CI	WIF not configured for this repo	Check iac-foundation service-wif layer
pip install from Artifact Registry fails	Missing keyring auth	Run pip install keyrings.google-artifactregistry-auth && gcloud auth application-default login

Where to find things

What you need	Where to look
How the system fits together	Architecture overview
Infrastructure and CI/CD	Platform docs
API Gateway and routing	API Gateway docs
Python package distribution	Distribution docs
Product-specific docs	Products
Operational runbooks	Operations
Architectural decisions	ADRs
Terminology	Glossary