Developer onboarding for external engineers should take about 10 working days and hit three milestones: working access and a running environment on day 1, a first merged pull request by day 5, and a first independent task by day 10. Contractors, augmented engineers and offshore teams need the same basics as new employees. On top of that they need tighter access control, clear legal paperwork and a plan for working across time zones.
This guide walks through each stage with the checklists and config files that make it repeatable. It ends with a day-by-day checklist you can drop into your team wiki.
Why onboarding external engineers is different
Most developer onboarding advice assumes a new full-time employee who will stay for years. External engineers change four things.
- Access has an end date. Every permission you grant must be easy to revoke on the day the engagement ends.
- Legal comes first. NDAs and intellectual property (IP) assignment must be signed before anyone sees the code.
- Communication is often asynchronous. The engineer may sit several time zones away, so written context matters more than hallway conversations.
- Ramp-up time is visible. You pay for every hour, so a slow onboarding shows up directly on an invoice.
None of this needs a heavy process. It needs a few decisions made before day 1 and a setup that any engineer can run without help.
Before day 1: access and legal checklist
Prepare access before the engineer starts. Waiting for permissions on day 1 is the most common onboarding failure, and the easiest to prevent.
Start with an access matrix. List every system, the level of access the role needs, who approves it and when it expires.
| System | Access level | Approver | Expires |
|---|---|---|---|
| Git repositories | Write on assigned repos only | Tech lead | End of engagement |
| CI/CD | Trigger and view builds | Tech lead | End of engagement |
| Cloud console | Read-only on staging | Platform lead | End of engagement |
| Staging database | Read-only, masked data | Platform lead | End of engagement |
| Chat and issue tracker | Member of project channels and board | Project manager | End of engagement |
| Production | None by default | Head of engineering | Granted per task, if ever |
Three rules keep this matrix safe:
- Sign the NDA and IP assignment before granting repository access. Make it a hard gate, not a reminder.
- Grant access through groups in your identity provider. If you use single sign-on, add the engineer to one group and let the group carry the permissions. Offboarding then becomes one removal, not a hunt across ten tools.
- Use masked or synthetic data outside production. External engineers rarely need real customer data to do their work.
Day 1: a dev environment that runs in one command
The goal for day 1 is simple: clone the repository, run one command, and see the tests pass in under an hour. If your setup guide has more than five manual steps, automate it.
A dev container gives every engineer the same toolchain regardless of their laptop. Here is a minimal .devcontainer/devcontainer.json for a Node.js project:
{
"name": "app-dev",
"image": "mcr.microsoft.com/devcontainers/typescript-node:20",
"features": {
"ghcr.io/devcontainers/features/docker-in-docker:2": {}
},
"forwardPorts": [3000],
"postCreateCommand": "make setup",
"customizations": {
"vscode": {
"extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"]
}
}
}
The postCreateCommand calls a single setup target. Keep that target in a Makefile so it also works outside the container:
.PHONY: setup test-smoke
setup:
[ -f .env ] || cp .env.example .env
docker compose up -d db
npm ci
npm run db:migrate
npm run db:seed
$(MAKE) test-smoke
test-smoke:
npm run test:smoke
Ask every new engineer to time the setup and report any step that failed. Fix those steps the same week. Each fix makes the next onboarding faster.
Days 2–5: codebase tour and the first merged PR
The first pull request matters more than its size. It proves the engineer can find code, follow your conventions and get through review. Pick a small, real task from a list of "good first issues" that you keep ready for new joiners.
Give the engineer three short documents, not a wiki dump:
- A one-page architecture diagram showing the main services, data stores and how requests flow between them.
- The architecture decision records (ADRs) that still matter, so they understand why things are the way they are.
- A list of good first issues, each with enough context to start without a meeting.
Make review ownership explicit. A CODEOWNERS file routes each pull request to the right reviewers automatically. See GitHub's documentation for the full syntax.
# .github/CODEOWNERS
# Default reviewers for everything
* @acme/core-reviewers
# Infrastructure and pipelines need the platform team
/infra/ @acme/platform
/.github/workflows/ @acme/platform
# Payment code needs a domain owner
/src/payments/ @acme/payments-owners
Turn on "Require review from Code Owners" in your branch protection rules so the file is enforced. Then add a pull request template so every PR answers the same questions:
## What changed
## Why
Closes #
## How to test
- [ ] Steps to reproduce or verify
## Checklist
- [ ] Tests added or updated
- [ ] No secrets or credentials in the diff
- [ ] Docs or ADR updated if behavior changed
Finally, name an internal buddy who commits to reviewing the engineer's pull requests within 24 hours during the first two weeks. Slow reviews hurt new joiners more than anything else, because they cannot move on to the next task with confidence.
Days 6–10: first independent task and working across time zones
By the second week, give the engineer a task they own from start to finish, with a clear definition of done. This is where time zones start to matter.
Agree on two things early:
- A fixed overlap window. Pick the same hours every day for live discussion and pairing. For example, an engineer in Vietnam (GMT+7) working with a team in London (GMT+0 in winter) gets only about 2–3 overlapping hours, late in the Vietnam afternoon. Decide on that window in week one, not when the first blocker appears.
- A daily written update. Three lines in the project channel: done, next, blocked. Your team can read it at the start of their day and unblock the engineer before the overlap window opens.
Record decisions in the ticket or pull request, not in chat. Chat scrolls away; tickets stay attached to the code.
Metrics that show onboarding is working
You cannot improve onboarding you do not measure. Track four numbers for every new engineer:
| Metric | What it tells you | Healthy target |
|---|---|---|
| Time to first commit | Whether access and setup work | 1–2 days after start |
| Time to first merged PR | Whether conventions and review flow work | By day 5 |
| PR review turnaround | Whether your team supports the new joiner | Under 24 hours |
| Blocking questions per day | Whether documentation answers the basics | Falling week over week |
Teams that place external engineers for a living track these numbers closely. InApps Technology, for example, targets a first commit within one to two weeks of a role brief, including matching the engineer to the team. That makes a useful benchmark for your own process.
Review the numbers at the end of week two. If time to first merged PR slipped, look at access and review speed before you look at the engineer.
Common onboarding failures
Most onboarding problems come from the receiving team, not the new engineer. Watch for these five:
- Access granted too late or too broadly. Late access wastes the first week. Broad access creates a security problem you will discover during offboarding.
- Outdated setup docs. If the README describes a setup that no longer works, the engineer loses a day and your trust.
- No named buddy. Without one person responsible for answering questions, questions go unanswered.
- Review queues measured in days. A new engineer with three open pull requests and no feedback stops making progress.
- One person holds all the knowledge. If only the external engineer understands a module, their exit becomes your outage.
That last failure is the most expensive. Pair external engineers with an internal owner for each module and require written notes on anything non-obvious. See knowledge silos and other staff augmentation risks for more ways to prevent it.
Developer onboarding checklist
Copy this checklist into your team wiki and assign an owner to each row. For a fuller template, the Microsoft Engineering Playbook onboarding guide is a good reference.
| Day | Task | Owner |
|---|---|---|
| Before day 1 | NDA and IP assignment signed | Project manager |
| Before day 1 | Identity provider group created, access matrix approved | Tech lead |
| Day 1 | Laptop or dev container running, make setup passes | Engineer |
| Day 1 | Intro call with buddy, overlap window agreed | Buddy |
| Day 2 | Architecture diagram and key ADRs read | Engineer |
| Day 2 | First good first issue assigned | Tech lead |
| Day 3–5 | First pull request opened and merged | Engineer, buddy |
| Day 6 | First independent task assigned with definition of done | Tech lead |
| Day 6–10 | Daily written update posted | Engineer |
| Day 10 | Onboarding metrics reviewed, setup doc fixes merged | Tech lead |
A good onboarding plan pays off twice. The engineer becomes productive sooner, and every fix you make along the way shortens the next onboarding.
