Guides
This page applies the model to a real workflow. Open the guides overview
Team workflows¶
Teams need one shared description of the project environment,
but they should not share real local values through Git.
envctl works well when the team shares intent and keeps machine truth local.
The problem this guide solves¶
In most teams, environment setup goes wrong in one of two ways:
- secrets drift into version control
- the repository stops describing what the application actually needs
Then onboarding turns into tribal knowledge:
- “copy my file”
- “ignore that variable”
- “CI uses something different”
- “I think this one is optional”
That is exactly the kind of ambiguity envctl is built to reduce.
The team rule that matters most¶
The repository should describe requirements.
Each machine should keep real values local.
That one split gives you:
- a contract the whole team can reason about
- local values that never need to be committed
- clearer onboarding
- less guesswork after pull
A normal team change¶
When the project itself needs a new variable, add it to the contract.
$ envctl add API_KEY
$ git add .envctl.yaml
$ git commit -m "require API_KEY"That change belongs in Git because it changes the project’s requirements.
What should not be committed is one developer’s actual API_KEY.
What the next developer does¶
After another developer pulls the contract change, the next step is not “copy someone else’s file”.
It is:
$ envctl check
$ envctl fill
$ envctl run -- python app.pyThat is the shape you want:
- pull shared requirements
- check
- fill only what is missing locally
- run
What gets shared and what stays local¶
Shared through Git¶
The team shares:
- the contract
- variable names
- required vs optional expectations
- defaults that are safe to publish
- descriptions and validation rules
Kept local¶
Each machine keeps:
- real credentials
- machine-specific URLs
- personal development overrides
- profile-local variants
That is the whole idea.
When to use add vs set¶
This distinction matters a lot in team workflows.
Use add when the project changes¶
Use add when the application now depends on a new variable as part of the shared contract.
That is a repository-level change.
Use set when only your machine changes¶
Use set when the contract stays the same, but your local machine needs a different value.
That is a local profile-level change.
A quick rule:
- project changed →
add - my machine changed →
set
A realistic onboarding flow¶
For a new teammate, the path should feel like this:
$ envctl config init
$ envctl init
$ envctl check
$ envctl fill
$ envctl run -- python app.pyNotice what is missing there:
- no secret files from another person
- no guessing which variables matter
- no “try this dotenv and see”
That is the payoff.
Team workflows with profiles¶
Sometimes one developer needs more than one local context for the same project.
For example:
- normal local development
- a second local integration setup
- a dedicated profile for another backend or account
That still does not require changing the contract.
It just means using profiles explicitly:
$ envctl profile create dev-alt
$ envctl --profile dev-alt fill
$ envctl --profile dev-alt checkHooks help teams, but they are not the whole story¶
Managed Git hooks are useful because they stop obvious mistakes before commit and push.
But hooks are local protection, not the entire team process.
A healthy team setup usually has all three:
- contract in Git
- local values outside Git
- CI validation after push
Read next¶
Vault¶
Reconnect team workflows to the local storage layer where real values live.