Stop Wasting Senior Engineer Time on New Hire Setup
Manual onboarding is a tax on productivity. Every new hire triggers a checklist that pulls a senior engineer away from actual work to click buttons in a dozen different admin panels. The process is slow, riddled with human error, and a security risk. A forgotten permission grant or a delayed account creation costs real money. We are not building a welcome wagon, we are building a user provisioning state machine.
The goal is to gut the manual labor from this process. We will ingest a single trigger event, a new employee record from HR, and use it to orchestrate account creation, permissioning, and software allocation across the entire stack. This is not about convenience. It is about enforcing consistency and reclaiming engineering hours.
Prerequisite: Define the Source of Truth and the Process
Before you write a single line of code, you must map the existing chaos. Your automation is only as good as the process it executes. If your current manual process is inconsistent, automating it just creates garbage faster. Get a definitive answer to what systems a new software engineer needs on day one. Does marketing need access to the production database? The answer is no, and the automation must enforce that boundary.
The source of truth is typically the Human Resources Information System (HRIS). Systems like Workday or BambooHR offer APIs that serve as the trigger. A “new hire” event in the HRIS becomes the webhook or API poll that kicks off the entire workflow. The data feed from these systems is often a low-pressure garden hose feeding a series of complex irrigation channels. You must sanitize and validate every field before it enters your logic.
You need a concrete list of deliverables for a new hire, categorized by role:
- Identity Provider: Okta, Google Workspace, Azure AD. This is the first gate.
- Communication: Slack, Microsoft Teams. Account creation and assignment to default channels.
- Version Control: GitHub, GitLab, Bitbucket. User creation and team assignment with read-only access by default.
- Cloud Provider: AWS, GCP, Azure. An IAM user or role with tightly scoped, minimal permissions.
- Project Management: Jira, Asana. Account and project board access.
Get this blueprint signed off. Any ambiguity here will surface as a production bug later.
Step 1: The Central Orchestrator
You need a central system to run the logic. You can buy this or build it. Buying it means an Identity Governance and Administration (IGA) platform. They are powerful, feature-rich, and wallet-drainers. Building it means a custom application or a set of serverless functions that you control completely. This route is cheaper upfront but saddles your team with long-term maintenance.
For a lean engineering team, a collection of AWS Lambda functions or Google Cloud Functions triggered by an event is a solid middle ground. It avoids server management and forces you into a modular design. Each function can be responsible for a single integration, like creating a Slack user or adding a developer to a GitHub team. This approach isolates failures. A broken Jira integration does not stop the AWS IAM user from being created.
We will proceed assuming a build-it approach using Python-based serverless functions. This gives us maximum control over the logic without the overhead of a dedicated server. Your orchestrator’s first job is to listen for the HRIS trigger and validate the incoming data payload. Is there an email? Is there a full name? Is the start date in a valid format? Reject incomplete records immediately and log the failure.
Step 2: Writs to the Identity Provider
The first real action is creating the core user identity. This is usually in Google Workspace or Azure AD. This account becomes the primary identifier for most downstream systems that support Single Sign-On (SSO). The API calls here are critical. A failure means nothing else in the workflow can proceed.
You will need a service account with user creation privileges. Lock this account down. It should have no other permissions. Store its credentials in a secrets manager like AWS Secrets Manager or HashiCorp Vault, not in environment variables or plaintext config files. A compromised onboarding script is like leaving the master key to the entire building under the welcome mat.
Here is a basic Python snippet using the `google-api-python-client` to create a user. It is stripped down for clarity, but you must inject robust error handling and logging.
from googleapiclient.discovery import build
from google.oauth2.service_account import Credentials
# Scopes define the permissions the service account needs
SCOPES = ['https://www.googleapis.com/auth/admin.directory.user']
SERVICE_ACCOUNT_FILE = 'path/to/your/credentials.json'
ADMIN_EMAIL = 'admin@yourdomain.com'
def create_google_workspace_user(first_name, last_name, primary_email, password):
"""
Creates a new user in Google Workspace.
Error handling is mandatory in a real implementation.
"""
creds = Credentials.from_service_account_file(
SERVICE_ACCOUNT_FILE, scopes=SCOPES, subject=ADMIN_EMAIL)
service = build('admin', 'directory_v1', credentials=creds)
user_body = {
"primaryEmail": primary_email,
"name": {
"givenName": first_name,
"familyName": last_name
},
"password": password,
"changePasswordAtNextLogin": True
}
try:
request = service.users().insert(body=user_body)
response = request.execute()
print(f"User created successfully: {response['primaryEmail']}")
return response['id']
except Exception as e:
# In production, this should log to a real monitoring system
print(f"Error creating user {primary_email}: {e}")
return None
Notice the `changePasswordAtNextLogin` flag. Force it to `True`. Never send plain text passwords over insecure channels like email. The initial password should be a one-time token.
Step 3: State Management and Idempotency
What happens if the Google user is created but the GitHub user creation fails because their API is down? If you re-run the process, you should not create a duplicate Google user. Your operations must be idempotent. This means running the process once has the same effect as running it ten times.
To achieve this, you need to track the state of each onboarding process. A simple DynamoDB table or even a PostgreSQL database works. When an onboarding request for `new.hire@company.com` comes in, you first check the database. Have we started this process? What step did we complete last? The primary key can be the new hire’s email address.
The state table might look like this:
- user_email (PK): new.hire@company.com
- status: in_progress
- last_completed_step: create_gsuite_account
- gsuite_user_id: 11223344556677889900
- github_username: null
- created_at: 2023-10-27T10:00:00Z
Before attempting to create a GitHub user, the orchestrator checks if `github_username` is null. If it is not, it bypasses that step. This design makes the system resilient to transient API failures and allows for safe retries.
Step 4: Role-Based Provisioning
Not every new hire is a software engineer. The HRIS data must contain a role or department field. The orchestrator uses this field to branch its logic. An engineer gets added to the `engineers` GitHub team, the `dev-access` AWS IAM role, and the `#engineering` Slack channel. A salesperson gets a Salesforce license and is added to the `#sales` channel.
Do not hardcode this logic. Use a configuration file (YAML, JSON) to map roles to resources. This allows you to update provisioning rules without changing the code. This configuration becomes a critical part of your infrastructure.
# roles.yaml
roles:
- name: software_engineer
permissions:
github_teams:
- engineers
- platform-tools
aws_iam_roles:
- arn:aws:iam::123456789012:role/DevReadOnly
slack_channels:
- engineering
- general
- random
- name: marketing_specialist
permissions:
github_teams: []
aws_iam_roles: []
slack_channels:
- marketing
- general
Your script parses this file to determine which APIs to call for a given role. This forces a structured approach to permissions and makes auditing simpler.
Step 5: The Offboarding Mirror
Provisioning is only half the problem. A proper automation strategy must include a clear, automated path for deprovisioning. When the HRIS fires a “termination” event, the entire onboarding process must run in reverse. Trying to un-bake a cake is impossible, and so is manually deprovisioning an employee from a dozen systems without a map.
Your state management database is that map. It contains the user IDs and resources allocated to each employee. The offboarding orchestrator reads this record and systematically revokes access. It suspends the Google Workspace user, removes them from GitHub teams, and detaches their IAM policies before queuing the user for deletion. The order of operations matters. Suspend the identity provider first to immediately cut off SSO access.
A failure in offboarding is a severe security incident. It leaves orphaned accounts with access to sensitive systems. The logging and alerting for this process must be more aggressive than for onboarding.
Step 6: Monitoring and Failsafes
This system will fail. APIs change without notice, network connections drop, and bad data will come from the HRIS. The difference between a good system and a bad one is how it fails. A good system fails loudly and safely.
Every step of the workflow must generate structured logs. Send these logs to a centralized system like Datadog, Splunk, or an ELK stack. Create alerts for critical failures. An inability to create a user in the primary identity provider should page the on-call engineer. A failure to add a user to a non-critical Slack channel can be a lower-priority ticket.
Build a dead-letter queue. If a function fails after multiple retries, push the event payload and error message to this queue. This prevents data loss and allows an engineer to manually inspect the failed event and re-process it after fixing the root cause. Without this, failed onboarding events are just lost to the void.
This is not a project you build once and forget. It is a living piece of infrastructure. It needs code reviews, maintenance, and periodic audits to ensure the permissions it grants still align with the principle of least privilege. The initial build is just the first step.