Quản lý Secrets với .env: Quy trình Git an toàn, không commit nhầm credentials
Hướng dẫn quản lý secrets với .env và Git: phân loại cấu hình, gitignore, env example, hooks, secret scanning, CI/CD, Next.js, Docker, rotation và incident response.
ShanverseUpdated 11 min read— viewsLoading views
Git
Secret Management
Secret là gì?
Một giá trị là secret khi người không được phép biết nó có thể giả mạo, truy cập dữ liệu hoặc nâng quyền:
Database password và connection string có credential.
API key, OAuth client secret và webhook signing secret.
JWT/session signing key.
Cloud access key, service-account key và private key.
Encryption key, KMS data key và certificate private key.
CI/CD token, package registry token và deploy token.
Không phải mọi environment variable đều là secret:
Phân loại đúng giúp tránh hai cực đoan: giấu mọi thứ gây vận hành khó, hoặc coi mọi config là vô hại.
Comments
Vì sao .env dễ gây sự cố?
.env là plaintext, thường nằm cạnh source code và được tool tự động load. Nó dễ bị:
git add . hoặc IDE Git UI đưa vào commit.
Copy vào Docker build context/image.
Upload trong debug bundle hoặc support archive.
In ra bằng console.log(process.env).
Thu thập bởi crash reporter, process dump hoặc CI logs.
Đồng bộ qua cloud drive/backup không đúng policy.
Chia sẻ qua chat, email hoặc screenshot.
.gitignore giảm nguy cơ commit nhầm nhưng không mã hóa file, không giới hạn process đọc được và không giải quyết rotation/auditing.
Cấu trúc file khuyến nghị
Quy tắc team:
Commit .env.example, không commit file chứa giá trị thật.
Production secrets đi qua secret manager hoặc platform secret store.
Mỗi environment có credential riêng.
Local dùng dev/sandbox secret, không dùng production credential.
Mỗi secret có owner, purpose, scope, expiry và rotation procedure.
.gitignore đúng ngay từ commit đầu
Ví dụ:
Sau khi thêm rule, kiểm tra:
git check-ignore -v cho biết rule nào đang match. Đừng dùng pattern quá rộng khiến file cần thiết bị ẩn ngoài ý muốn.
Bỏ track file nhưng giữ bản local:
Lệnh này chỉ ngăn các commit tiếp theo. Secret vẫn nằm trong commit cũ và phải được rotate; history cleanup là bước riêng.
.env.example phải hữu ích nhưng không chứa secret
Giá trị mẫu phải rõ là placeholder. Không dùng secret “tạm” nhưng thật, token sandbox dùng chung hoặc credential production đã được che một phần.
Tài liệu nên ghi cách lấy secret:
Nếu có CLI vault, ưu tiên inject vào process hoặc tạo file tạm với permission chặt và TTL ngắn.
Validate environment khi ứng dụng khởi động
Đừng để thiếu biến đến khi request production đầu tiên mới lỗi.
Lưu ý:
Validate presence, type, range và environment-specific rules.
Không đưa giá trị secret vào error.
Chỉ export object config cần thiết, không truyền toàn bộ process.env.
Không có default yếu cho secret production.
Sai:
Nếu cấu hình production thiếu, app nên fail fast thay vì âm thầm dùng khóa mặc định.
Next.js: NEXT_PUBLIC_ nghĩa là công khai
Trong Next.js, biến có prefix NEXT_PUBLIC_ được inline vào JavaScript bundle cho browser ở build time.
Không bao giờ:
Ngoài ra, giá trị khai báo qua next.config.jsenv có thể được đưa vào bundle. Secret-bearing module chỉ được import từ Server Components, Route Handlers, Server Actions hoặc server-only code; nhưng Server Actions vẫn phải kiểm tra authorization.
Không dựa vào tên biến để tự trấn an. Kiểm tra build artifact/source maps và network payload để chắc secret không bị serialize.
NestJS và server runtime
Load config trong server process, không trả config object qua controller.
Validate bằng schema hoặc ConfigModule khi bootstrap.
Service chỉ đọc secret cần thiết, không inject toàn bộ environment.
Không log config khi startup.
Tách secret cho auth, database, queue và third-party integration theo least privilege.
Restart/rollout an toàn khi secret rotate; hỗ trợ overlap nếu protocol cần.
Environment variables có thể đọc bởi process con, debug tooling hoặc platform operators tùy hệ thống. Với high-value secrets, ưu tiên workload identity hoặc runtime fetch từ secret manager.
Local development workflow
Một quy trình tốt:
Clone repository; .env.example có sẵn.
Authenticate bằng developer identity tới secret manager.
Lấy development-only credentials có scope thấp và TTL ngắn.
Inject secrets vào shell/process hoặc tạo .env.local được ignore.
Chạy validation/bootstrap check.
Trước commit, xem git diff --cached.
Secret scanner chạy trong pre-commit và CI.
Khi kết thúc/đổi dự án, revoke local credentials và xóa file.
Không gửi .env trong Slack/email. Chia sẻ reference/path và quyền truy cập, không chia sẻ giá trị.
Pre-commit hook: lớp bảo vệ sớm
Hook có thể chạy Gitleaks/TruffleHog hoặc scanner tương đương trên staged diff:
Hoặc dùng framework hook của team. Tuy nhiên:
Local hook có thể không được cài hoặc bị bypass bằng --no-verify.
Scanner có false positive/false negative.
Custom secret format có thể không được nhận diện.
Vì vậy hook chỉ là lớp feedback nhanh, không phải enforcement duy nhất.
CI và server-side protection
Pipeline nên:
Scan full repository/history khi onboarding.
Scan commit/PR diff ở mỗi CI run.
Bật GitHub secret scanning và push protection khi khả dụng.
Block merge/push khi phát hiện credential hợp lệ.
Có quy trình review bypass với reason, owner và audit.
Scan artifacts, container image và IaC—not chỉ source files.
Push protection chặn secret trước khi tới repository, nhưng không bắt mọi secret tự định nghĩa. Thêm custom patterns cho token nội bộ và high-risk formats.
Không dùng allowlist theo giá trị secret thật. Nếu phải suppress false positive, scope suppression hẹp theo rule/path và review định kỳ.
CI/CD: tránh secret tĩnh
Ưu tiên federation/workload identity:
Mermaid
Loading diagram…
Thay vì lưu cloud access key sống nhiều năm:
CI nhận identity token ngắn hạn.
Cloud IAM kiểm tra repository, branch, environment và workflow claims.
Phát credential tạm có least privilege.
Credential hết hạn sau job.
Nếu buộc dùng stored secret:
Scope theo environment/repository.
Chỉ expose ở job cần dùng.
Không chạy untrusted fork PR với production secrets.
Mask logs nhưng không tin masking là bảo vệ tuyệt đối.
Không echo, dump environment hoặc bật shell tracing set -x quanh secret.
Rotate định kỳ và sau personnel/incident changes.
Docker: đừng bake secret vào image
Sai:
Build args có thể xuất hiện trong image history/provenance; ENV tồn tại trong image/runtime layers.
Dùng BuildKit secret mount:
Build:
Thêm .env*, .git và credential files vào .dockerignore để chúng không vào build context:
Runtime secret nên được orchestrator mount/inject, không COPY vào image.
Kubernetes và cloud platforms
Kubernetes Secret chỉ là API object; base64 không phải encryption. Cần:
Encryption at rest cho control plane.
RBAC least privilege.
External Secrets/CSI integration với vault khi phù hợp.
Namespace/service-account isolation.
Không đưa Secret manifest plaintext vào Git; dùng encrypted GitOps format nếu có policy và key management tốt.
Audit access và rotation.
Tốt hơn static cloud key là workload identity gắn với service account/pod/task.
Logging và observability
Không log:
process.env toàn bộ.
Authorization headers/cookies.
Database URLs có password.
Request/response body chứa credentials.
Secret-manager response.
Dùng structured redaction theo key và pattern. Nhưng key-based redaction không đủ nếu secret nằm trong URL hoặc field tên lạ.
Không đưa secret vào metric label, trace attribute, exception message hoặc support ticket.
Nếu lỡ commit secret: phản ứng đúng thứ tự
1. Revoke hoặc rotate ngay
Disable key/token cũ.
Phát credential mới với scope tối thiểu.
Cập nhật services qua secret manager.
Kiểm tra service hồi phục.
Đây là bước quan trọng nhất. Không chờ dọn history xong.
2. Điều tra phạm vi
Secret xuất hiện từ commit nào, branch/tag nào?
Repository public hay private, ai có quyền clone?
Có fork, PR diff, CI log/artifact, package/image hay backup không?
Secret đã được sử dụng bất thường chưa?
Có secret khác cùng file cần rotate không?
3. Dọn history khi cần
Dùng git-filter-repo hoặc quy trình được host khuyến nghị. History rewrite thay đổi commit hashes, yêu cầu force push, phối hợp contributor và xử lý tags/branches/forks.
Dọn history giảm khả năng phát hiện lại nhưng không thay rotation.
4. Ngăn tái diễn
Thêm .gitignore/.dockerignore.
Bật push protection và secret scanning.
Thêm custom patterns.
Sửa onboarding/bootstrap.
Giảm scope/lifetime của credential.
Viết incident report không chứa secret value.
.gitignore không phải security boundary
Các hiểu lầm phổ biến:
“Đã ignore nên file an toàn.” File vẫn plaintext trên máy.
“Repo private nên commit secret được.” Insider, token compromise, fork, CI và backup vẫn là risk.
“Xóa commit là xong.” Secret phải rotate.
“Environment variable luôn an toàn.” Có thể leak qua log, dump, child process hoặc bundle.
“Secret scanner bắt được tất cả.” Scanner là defense-in-depth.
“Base64 là mã hóa.” Không phải.
“Build arg không nằm trong image cuối nên an toàn.” Có thể lộ qua history/provenance/cache.
Secret lifecycle trưởng thành
Mỗi secret nên có:
Owner và system sử dụng.
Mục đích và data classification.
Scope/permissions tối thiểu.
Nơi lưu chuẩn.
Thời điểm tạo và expiry.
Rotation frequency và procedure.
Dependencies/consumers.
Revocation path.
Audit/alert rules.
Ưu tiên credential ngắn hạn, dynamic secret và workload identity. Secret không có owner hoặc không biết nơi dùng là secret không thể rotate an toàn.
Checklist cho repository
.env, .env.*, private keys và credential files nằm trong .gitignore.
.env.example chỉ chứa placeholder.
.dockerignore loại .env*, .git và key files.
git check-ignore -v được kiểm tra trong bootstrap test.
App validate env khi startup và fail fast.
Không secret nào dùng NEXT_PUBLIC_ hoặc next.config.js env.
Pre-commit scanner cho feedback sớm.
CI scan PR/commit và server-side push protection được bật.
Custom token patterns có rule riêng.
CI dùng OIDC/workload identity khi có thể.
Production secrets nằm trong secret manager, không trong .env repo.
Docker build dùng secret mount, không ARG/ENV cho secret.
Logs, traces, metrics và errors có redaction.
Mọi secret có owner, scope, expiry và rotation runbook.
Leak response bắt đầu bằng revoke/rotate, không phải chỉ xóa Git history.
Kết luận
Không commit nhầm .env không thể dựa vào trí nhớ của từng developer. Workflow an toàn cần nhiều lớp: file mẫu không có giá trị thật, ignore rules đúng từ đầu, secret manager, startup validation, local hook, CI scanning và push protection.
Quan trọng hơn, hãy giảm giá trị của mọi lần rò rỉ: credential riêng theo environment, least privilege, TTL ngắn và rotation tự động. Khi secret không nằm trong Git và có lifecycle rõ ràng, .env trở lại đúng vai trò—một tiện ích local, không phải kho bí mật của hệ thống.
Table of contents(24)
Codejavascript
1# Public configuration2APP_ENV=development3LOG_LEVEL=debug4NEXT_PUBLIC_ANALYTICS_ID=public-id56# Secrets7DATABASE_URL=postgres://user:password@host/db8SESSION_SECRET=...9STRIPE_SECRET_KEY=...
Codeplain text
1.env.example # Commit: chỉ tên biến + giá trị giả2.env.local # Không commit: local của developer3.env.test.local # Không commit: test credentials cục bộ4.env.production # Không commit; tốt hơn là không tồn tại trong repo/workstation5.envrc # Chỉ commit nếu không chứa secret
Codeplain text
1# Environment files2.env3.env.*4!.env.example5!.env.*.example67# Local secrets8*.pem9*.key10secrets/11credentials.json
Codeplain text
11. Authenticate to the company secret manager.22. Request access to the development path.33. Run the approved bootstrap command.44. Never paste production values into local .env files.
Codedocker
1ARG NPM_TOKEN2ENV NPM_TOKEN=$NPM_TOKEN3RUN npm ci
Codedocker
1# syntax=docker/dockerfile:12RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \3 npm ci
Codebash
1gitcheck-ignore-v.env.local2gitstatus--ignored
Codebash
1gitrm--cached.env2gitcommit-m"stop tracking local environment file"
Hướng dẫn bảo mật Git repository khi lộ API key hoặc password trên GitHub: rotate credential, xóa lịch sử với git-filter-repo/BFG, force push, xác minh và phối hợp team.
Hướng dẫn cấu hình .gitignore chuẩn cho dự án Git, Node.js và Next.js: cú pháp pattern, bảo vệ file .env, bỏ qua node_modules, xử lý file đã tracked và kiểm tra rule hiệu quả.
Hướng dẫn Git Aliases và .gitconfig thực chiến: alias an toàn, log đẹp, cấu hình pull/push/rebase, includeIf cho tài khoản work/personal, bảo mật và chia sẻ dotfiles.
