Git and Repository Preparation
A safe self-hosted deployment starts from an understood repository, a specific release or commit, reviewed deployment files, and a documented relationship to upstream updates.
What You Will Be Able to Decide
- Explain the role of git and repository preparation in a self-hosted system.
- Apply the procedure to a real open-source deployment.
- Recognise unsafe defaults and verify the resulting control.
- Record enough evidence for another operator to repeat or recover the work.
Git records the history of source and configuration. In self-hosting, it also supplies the coordinates for answering what is running, what changed, and how to return to a known state.
Deploying the default branch without reading the project documentation outsources production stability to whatever changed most recently. A release tag or immutable commit gives the deployment an identity.
You do not need to become a full-time maintainer. You do need to understand the licence, supported deployment method, release cadence, data locations, upgrade notes, and security communication channel.
Technical term
Pinned revision
A named release, commit hash, or immutable image digest selected as the exact version to deploy.
It is a recipe edition with a page number, rather than an instruction to cook whatever happens to be on the author's desk today.
The Working Model
Begin with the upstream README and deployment documentation, then inspect the licence, releases, issues, and security policy. A repository can be active and still be unsuitable for the data or availability requirement.
Fork only when you expect to maintain changes. Otherwise keep a small deployment repository containing Compose files, environment examples, reverse-proxy configuration, and operational notes while consuming an upstream image at a pinned version.
Never commit live secrets. Commit an `.env.example` containing names and safe placeholders, ignore the real `.env`, and make configuration changes through reviewed commits so deployment history remains explainable.
Implementation Procedure
- Record the upstream repository URL, licence, latest stable release, supported database, and documented backup method.
- Clone or create the deployment repository and choose a branch protection and review approach proportionate to the team.
- Pin images to a release tag or digest rather than relying on `latest`.
- Commit Compose, `.env.example`, runbooks, and a change log while excluding live credentials and application data.
- Create a test branch for the first upgrade and record the rollback revision before merging.
git clone https://github.com/example/project-deployment.git
cd project-deployment
git switch -c deployment/initial
git add compose.yaml .env.example README.md
git commit -m "Document initial self-hosted deployment"
git log --oneline --decorate -5Controlled Practice and Fragile Practice
Verification and Recovery Evidence
- A fresh clone contains enough documentation to recreate the non-secret deployment structure.
- The running image can be traced to a release or digest.
- Repository secret scanning and ignore rules do not report live credentials.
Warning Signs
- The deployment depends on uncommitted changes on one laptop.
- An image uses the `latest` tag and nobody records what it resolved to.
- The only upgrade plan is to pull and hope.
Questions to Ask a Consultant
- Can the running version be identified without logging into the server?
- Which local changes must be carried through future upstream releases?
- Does the repository contain configuration history without containing secrets?
Key takeaway
Key Takeaway
Git makes deployment explainable when versions are pinned, secrets stay out of history, and every change has a reversible reference.