Technical Onboarding Guide Template

Day 1: Access & Environment

Goal: end the day with a working dev environment and the app running locally.

Get Access

• GitHub / GitLab org — can clone repos

• Slack — joined team channels

• CI/CD system (GitHub Actions, CircleCI, etc.) — can see builds

• Cloud console (AWS, GCP, Azure) — read access to staging

• Error tracking (Sentry, Datadog, etc.) — can see errors

• Issue tracker (Jira, Linear, GitHub Issues) — can see the board

• Internal docs / wiki — can browse

Set Up Your Machine

Install prerequisites and get the project running:

# 1. Clone the repo
git clone git@github.com:org/repo.git && cd repo

# 2. Install dependencies
# adapt to your stack: npm install, bundle install, pip install, etc.

# 3. Set up environment variables
cp .env.example .env
# Fill in values — ask your buddy for dev secrets

# 4. Start infrastructure (database, cache, etc.)
docker compose up -d

# 5. Run migrations and seed data
# adapt: rails db:setup, npm run migrate, etc.

# 6. Start the dev server
# adapt: npm run dev, make dev, etc.

# 7. Open http://localhost:3000 and verify it works

Week 1: Learn the System

Goal: understand the architecture, the codebase, and how the team works well enough to make your first contribution.

Understand the Architecture

Read or ask about these — you don't need to memorize everything, just build a mental map:

• What are the major components / services and what does each one do?

• How does data flow from user action to database and back?

• Where does the app run? (cloud provider, region, container orchestration)

• What are the main data stores and why were they chosen?

• What are the external integrations and how do they work?

Key architecture docs to read:

Learn the Codebase

• Read the README and any CONTRIBUTING guide

• Read the 5 most recent merged PRs — see the style, scope, and review process

• Find where the main entry point is and trace a request end-to-end

• Find where tests live and run them — make sure they pass

• Identify the areas of the codebase that are well-documented vs. tribal knowledge

Learn the Workflow

Week 1: First Contribution

Ship something small. The goal is to go through the full cycle — write code, open a PR, get it reviewed, see it merge — before tackling anything complex.

• Pick a starter ticket (ask your buddy or manager to suggest one)

• Write the code and tests

• Open a PR and request review

• Address feedback and get it merged

• Verify it works in staging

Weeks 2-4: Go Deeper

You can run the app, you've shipped a PR, you know where to find things. Now build real context.

• Take on a medium-sized feature or bug fix

• Pair with a teammate on a part of the codebase you haven't touched

• Shadow an on-call shift or incident review to see how the team debugs production issues

• Set up monitoring dashboards in your browser — watch the system behave

• Review PRs from teammates — this is the fastest way to learn the codebase

• Ask your buddy or manager: "What do I not know that I don't know I don't know?"

Key People

Useful Links

Notes & Questions

Use this space to jot down things you learn, questions you want to ask, or surprises you encounter. Review these with your buddy or manager in your first few 1:1s.

• Question or observation