Developer Onboarding Checklist

A developer onboarding checklist for engineering teams: repo access, local setup, first PR, deploy rights and on-call, so new engineers ship in week one.

Typical schedule per new engineer
The checklist 5 sections, 21 items
Variables {{engineer_name}} {{buddy}}
Start from CI

Use this template Free, no credit card. Imports the checklist into your Runbook organization.

Use this checklist when a software engineer joins the team, whether as an employee or as a long-term contractor. It starts where general IT onboarding ends: the person has a laptop and an email account, and now needs to get from "can log in" to "has shipped a change to production".

Who owns it

The engineering manager owns the run. A named buddy, an engineer on the same team, does most of the items with the new hire and answers the questions they would not ask in a channel. Assign the access items to whoever administers each system, so the run shows who granted what.

Common pitfalls

The setup guide is out of date. Every new hire discovers it on day one. Ask them to fix the README as they go. That is a good first pull request.
Production access on day one. New engineers rarely need it in week one. Grant read access to logs and dashboards first, and deploy rights once they have shipped a reviewed change.
No small first task. A vague "explore the codebase" week is demotivating. Pick a small, real ticket before the start date.
Secrets shared in chat. Send local .env values through the password manager or a secrets tool, never as a chat message.
On-call too early. Shadow at least one rotation before taking the pager alone.

If you manage group membership in code or in your identity provider, start the run from that event. The checklist then appears automatically with the buddy filled in.

The checklist: Onboard engineer {{engineer_name}}

Before the start date

Buddy {{buddy}} is assigned and has time blocked in the first week
A small, well-defined first ticket is picked and assigned to {{engineer_name}}
Ideal first tickets touch real code, need a review and can ship to production within days.
Setup guide in the main repository README was checked in the last month optional

Access

Added to the source control organisation and the team's repositories
For example GitHub, GitLab or Bitbucket. Grant through a team, not per repository.
SSH or signing key registered and MFA enforced on the source control account
Access to the issue tracker and the team board
Read access to logs, error tracking and dashboards
Access to staging or a personal development environment
Development secrets shared through the password manager or secrets tool
Added to team channels, the incident channel and engineering meetings

Local setup

Repository cloned and the application runs locally
Test suite runs locally and passes
Linters, formatters and pre-commit hooks installed
Setup guide corrected for anything that did not work optional

First week

Architecture walkthrough with {{buddy}}: main services, data stores and how they connect
Walkthrough of the deploy process and the rollback procedure
First pull request opened, reviewed and merged
First change deployed to production with {{buddy}} watching

First month

Deploy rights granted after the first reviewed change has shipped
Incident process and runbooks read, and one on-call shift shadowed optional
Feedback on onboarding collected from {{engineer_name}} and this template updated

Checklist as Markdown

# Onboard engineer {{engineer_name}}

## Before the start date
- [ ] Buddy {{buddy}} is assigned and has time blocked in the first week
- [ ] A small, well-defined first ticket is picked and assigned to {{engineer_name}}
  Ideal first tickets touch real code, need a review and can ship to production within days.
- [ ] Setup guide in the main repository README was checked in the last month (optional)

## Access
- [ ] Added to the source control organisation and the team's repositories
  For example GitHub, GitLab or Bitbucket. Grant through a team, not per repository.
- [ ] SSH or signing key registered and MFA enforced on the source control account
- [ ] Access to the issue tracker and the team board
- [ ] Read access to logs, error tracking and dashboards
- [ ] Access to staging or a personal development environment
- [ ] Development secrets shared through the password manager or secrets tool
- [ ] Added to team channels, the incident channel and engineering meetings

## Local setup
- [ ] Repository cloned and the application runs locally
- [ ] Test suite runs locally and passes
- [ ] Linters, formatters and pre-commit hooks installed
- [ ] Setup guide corrected for anything that did not work (optional)

## First week
- [ ] Architecture walkthrough with {{buddy}}: main services, data stores and how they connect
- [ ] Walkthrough of the deploy process and the rollback procedure
- [ ] First pull request opened, reviewed and merged
- [ ] First change deployed to production with {{buddy}} watching

## First month
- [ ] Deploy rights granted after the first reviewed change has shipped
- [ ] Incident process and runbooks read, and one on-call shift shadowed (optional)
- [ ] Feedback on onboarding collected from {{engineer_name}} and this template updated

Start this checklist from your pipeline

When an engineer is added to the engineering group, POST /api/v1/runs with template "Onboard engineer {{engineer_name}}" and buddy.

curl -X POST https://runbook.metastic.ch/api/v1/runs \
  -H "Authorization: Bearer $RUNBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "Onboard engineer {{engineer_name}}", "variables": {"engineer_name": "…", "buddy": "…"}}'

See the API and the GitHub Action

Frequently asked questions

How long should developer onboarding take?

Aim for a first merged change in the first week and a production deploy soon after. Being fully productive on an unfamiliar codebase takes longer, often a few months. The checklist covers the mechanical part, so the time goes to learning the system rather than to waiting for access.

What makes a good first task for a new developer?

A small bug fix or minor feature that touches real code, needs a code review and can be deployed quickly. It should not be urgent or on the critical path. The goal is to walk through the whole workflow once, from ticket to production.

Should new engineers get production access immediately?

Usually not. Read access to logs and monitoring is useful from day one. Write or deploy access can wait until the person has shipped a reviewed change and understands the rollback procedure. Grant it through a group, so it is easy to review later.

Updated 2026-11-04