Local Development Onboarding

How a new contributor gets from git clone to a passing local task build + task lint.

For most repositories this is just task setup. For repositories that consume private @ontopix packages there is one prerequisite that is easy to miss: local dependency installation needs an AWS CodeArtifact token. This page makes that prerequisite explicit so onboarding does not silently break.

TL;DR

• No private @ontopix dependencies → task setup works with zero AWS access.
• Consumes private @ontopix dependencies → you need AWS access with CodeArtifact read permission before task setup:install can run locally.
• No AWS access? That is fine — CI is the authoritative build/lint gate and authenticates via OIDC. You can develop against tests/types and let CI prove the build.

The happy path

git clone https://github.com/ontopix/<repo>.git
cd <repo>
task setup        # prepare .env, authenticate the registry, install deps
task lint:check   # or: task ci:lint / task lint:all
task build        # or: task build:lambda / task ci:build

If task setup completes, build and lint will run. The only step that can fail for reasons outside the repo is registry authentication — covered below.

Run task --list in any repo to see the exact task names; namespaces (lint:*, build:*, ci:*) are standardized by the Taskfile contract.

Does this repo need AWS access to build locally?

Two distinct uses of CodeArtifact exist. Only the first blocks a local build/lint.

Quick check:

# If this prints a registry line, the repo consumes private packages:
grep '@ontopix:registry' .npmrc 2>/dev/null
# If this lists a task, setup will try to mint a CodeArtifact token:
task --list | grep 'setup:registry'

As of this writing, transcript-service and enrich-service are consumers (the prerequisite applies). sluice and ledger are publishers only (local build/lint works with no AWS access; AWS is needed for release:publish:*).

What happens during task setup

task setup is the canonical first-use entry point (ADR-0014). It runs three phases in order:

1. setup:prepare — copies .env.example → .env if missing. No credentials needed.
2. setup:registry — mints a CodeArtifact authorization token and writes NPM_TOKEN into .env. This is the step that needs AWS access. It runs, in effect:

   aws codeartifact get-authorization-token \
     --domain ontopix \
     --region eu-central-1 \
     --query authorizationToken --output text
   

3. setup:install — pnpm install, reading NPM_TOKEN from .env (the .npmrc references ${NPM_TOKEN}). Without a valid token, the private @ontopix packages 401 and install fails — so build/lint never get a chance to run.

The phases are independently invocable, so you can refresh just the token without reinstalling (see Token expiry).

Getting CodeArtifact access (consumer repos)

You need an AWS principal in the Ontopix account that can read CodeArtifact:

• AWS access to the Ontopix account, typically via SSO / a named CLI profile (e.g. AWS_PROFILE=ontopix-dev in your .env).
• The CodeArtifactReadAccess permission on that principal (read-only; covers GetAuthorizationToken + read on the ontopix domain). This is the same permission CI's GitHubActions-CodeArtifact-ReadRole carries — see the CodeArtifact pattern.

How to request it: ask the infrastructure owners for read access to the ontopix CodeArtifact domain (eu-central-1). The owning team is defined in CODEOWNERS in ontopix/infra (.infra / global/codeartifact/); open an issue there or ask in the engineering Slack. State which repos you are onboarding into so they grant the read policy.

Once your profile is configured:

aws sso login --profile ontopix-dev   # or however you authenticate
export AWS_PROFILE=ontopix-dev         # or set it in .env
task setup                             # setup:registry now succeeds

Token expiry

CodeArtifact authorization tokens are short-lived (up to 12 hours). When pnpm install starts returning 401, the token expired. Refresh it without a full reinstall:

task setup:registry   # re-mints NPM_TOKEN into .env

No AWS access? CI is the source of truth

Local CodeArtifact auth is a developer convenience, not the authoritative build gate. CI authenticates to CodeArtifact via GitHub OIDC (no human credentials, no stored secrets) and runs the same task targets. This is by design for private packages — see the CodeArtifact + GitHub Actions pattern.

If you do not (yet) have CodeArtifact access, you can still contribute:

• Push your branch and open a PR — CI runs lint + build + test and is the authoritative pass/fail signal.
• Work on anything that does not require installed private deps (docs, reading code, design).
• Request CodeArtifact access in parallel (above) so you can iterate locally.

What you cannot do without a token is run task setup:install / task build / task lint locally for a consumer repo, because the private dependencies will not install. That is expected, not a misconfiguration.

Troubleshooting

Related

• CodeArtifact + GitHub Actions — how OIDC auth and the read/publish roles work
• ADR-0014: setup:* namespace — why setup:registry is a distinct phase
• Taskfile as Contract — standard setup:*, lint:*, build:*, ci:* task names
• Repository Structure — the Minimum Viable Repository