TCP connection timeouts on a VPS can cause websites to become unreachable, applications to stop…
Git Deployment Workflow VPS: Complete Setup Guide

A Git deployment workflow VPS setup helps you deploy application updates from a Git repository to a production server in a consistent and secure way. Instead of manually uploading files, you can manage application releases, configure environment variables, maintain correct file permissions, and roll back to a previous version when something goes wrong.
In this guide, you will learn how to configure a Git-based deployment workflow on a Linux VPS using Git, SSH authentication, a dedicated deployment user, release directories, and practical rollback procedures.
What Is a Git-Based Deployment Workflow?
A Git-based deployment workflow is a process that uses a Git repository as the source of your application code. Instead of manually copying files to your server, you retrieve a specific version of the project from a repository such as GitHub, GitLab, or a self-hosted Git server.
A typical workflow looks like this:
- Develop and test changes on your local computer.
- Commit the changes and push them to the Git repository.
- Connect to your VPS or trigger an authorized deployment process.
- Download the intended version of the application.
- Configure dependencies, permissions, and environment variables.
- Activate the new release and restart the application if required.
- Verify the deployment and roll back if something goes wrong.
Git tracks code changes, but it does not automatically handle every part of production deployment. Database migrations, dependency installation, application restarts, secret management, and health checks still need to be configured for your particular application.
Why Use Git for VPS Deployment?
Using Git for deployment offers several practical advantages over manual file transfers.
Version control: Every release can be associated with a commit or tag, making it easier to identify exactly which code is running.
Consistent deployments: A documented process reduces the chance of forgetting files or applying changes in the wrong order.
Faster updates: You can retrieve the required code directly from the repository rather than uploading an entire project manually.
Safer rollbacks: A release-based workflow lets you switch back to an earlier version of the application code.
Better collaboration: Multiple developers can contribute changes through branches and pull requests while maintaining a shared deployment process.
Improved security: A dedicated deployment account and SSH key can limit the permissions required to publish application updates.
These benefits become especially useful when maintaining production websites, APIs, business applications, and customer-facing services on a Linux VPS.
Prerequisites
Before starting, make sure you have the following:
- A Linux VPS running a supported distribution, such as Ubuntu or Debian.
- SSH access with administrative privileges for initial server configuration.
- Git installed on the server.
- A Git repository containing your application code.
- A domain name and web server, if you are deploying a public website.
- A basic understanding of Linux commands and file permissions.
You should also know how your application is started. A PHP application served by Nginx or Apache has different deployment requirements from a Node.js API managed by systemd or a Python application running through Gunicorn.
The commands below assume an Ubuntu or Debian-based server and a private Git repository. Replace example usernames, repository URLs, and application paths with your actual values.
Step 1: Install Git on Your VPS
Connect to your server over SSH:
ssh your_admin_user@YOUR_SERVER_IP
Update the package index and install Git:
sudo apt update
sudo apt install git -y
Confirm the installation:
git --version
Git should return its installed version.
You can also configure a default author identity for commits made directly on the server:
git config --global user.name "Server Deployment"
git config --global user.email "[email protected]"
This identity is mainly relevant if you create commits from the server. A deployment-only account normally should not modify or commit application code.
Step 2: Create a Dedicated Deployment User
Avoid running routine deployment commands as root. A dedicated account limits the consequences of mistakes and makes it easier to control which files the deployment process can modify.
Create a deployment user:
sudo adduser deploy
Follow the prompts to create the account. You do not need to add this account to the sudo group for the workflow described here.
Create a directory for the application:
sudo mkdir -p /var/www/myapp
sudo chown deploy:deploy /var/www/myapp
Switch to the deployment account:
sudo -iu deploy
Create the initial directory structure:
mkdir -p /var/www/myapp/releases
mkdir -p /var/www/myapp/shared
The directory layout will eventually look like this:
/var/www/myapp/
├── current -> releases/20261112-120000
├── releases/
│ ├── 20261111-100000/
│ └── 20261112-120000/
└── shared/
└── .env
The releases directory stores separate application versions. The current symbolic link identifies the active release, while shared holds files that should persist across deployments.
This separation makes rollback easier and prevents a new release from immediately overwriting the previous application code.
Step 3: Configure SSH Authentication for Your Git Repository
If your repository is private, the VPS needs a secure way to authenticate with your Git provider.
Create a dedicated SSH key while logged in as the deployment user:
ssh-keygen -t ed25519 \
-C "vps-deployment" \
-f ~/.ssh/id_ed25519
Protect the key with a passphrase where your deployment method supports it. For unattended deployment, consider a narrowly scoped deploy key or a managed credential mechanism appropriate for your Git provider.
Display the public key:
cat ~/.ssh/id_ed25519.pub
Add this public key to the repository’s deploy-key settings. Grant read-only access unless your deployment process genuinely needs to push changes back to the repository.
Never share or upload the private key file (id_ed25519). Only the public key should be added to the Git provider.
Before trusting a repository host, verify its SSH host-key fingerprint against the provider’s official documentation or another trusted source. Then test the connection using the SSH instructions for your Git provider.
For GitHub, a typical test is:
ssh -T [email protected]
A successful authentication message confirms that the key is recognized. GitHub may still display a message explaining that shell access is unavailable; this is normal for Git-only access.
Step 4: Prepare the Production Environment
Your production application should not depend on configuration files or credentials committed to the Git repository.
Create an environment file outside the release directories:
nano /var/www/myapp/shared/.env
Add the variables required by your application. For example:
APP_ENV=production
APP_DEBUG=false
APP_URL=https://example.com
DB_HOST=127.0.0.1
DB_DATABASE=production_db
DB_USERNAME=app_user
DB_PASSWORD=replace_with_a_real_secret
These are illustrative variables. Use the names and format expected by your application, and replace all example values before deployment.
Restrict access to the file:
chmod 600 /var/www/myapp/shared/.env
Check that the file belongs to the deployment account:
ls -l /var/www/myapp/shared/.env
Your web server or application process may need access to some configuration files, but avoid making the file world-readable. Use a carefully planned group or service-account permission model if the application runs under a different user.
Also make sure .env and other secrets are excluded from version control. For example, add the following to .gitignore if appropriate for your application:
.env
.env.*
!.env.example
Review this pattern before using it, particularly if your project intentionally tracks a non-secret environment template. Never commit real database passwords, API tokens, private keys, or production credentials.
Step 5: Create Your First Release
Switch to the deployment account if you are not already using it:
sudo -iu deploy
Set the repository URL. For a private GitHub repository, it may look like this:
REPO_URL="[email protected]:YOUR_ORG/YOUR_REPO.git"
Create a release directory using a timestamp:
RELEASE_ID=$(date +%Y%m%d%H%M%S)
RELEASE_DIR="/var/www/myapp/releases/$RELEASE_ID"
mkdir -p "$RELEASE_DIR"
git clone --depth 1 --branch main \
"$REPO_URL" "$RELEASE_DIR"
The command downloads the latest available commit on the main branch at the time of cloning. The --depth 1 option reduces the amount of Git history downloaded, which is useful when you only need the current code.
For production systems, deploying an explicitly selected commit or immutable release tag is more predictable than always deploying whatever happens to be at the branch tip.
For example, you can replace the branch name with a release tag after verifying that the tag exists in your repository.
Once the repository has been cloned, link the shared environment file into the release:
ln -s /var/www/myapp/shared/.env \
"$RELEASE_DIR/.env"
If your application uses persistent uploads, storage directories, or other runtime files, link those from the shared directory as well. Do not blindly share the entire application directory, because doing so can undermine release isolation.
Step 6: Install Dependencies and Prepare the Application
The commands needed here depend on your technology stack.
For a PHP application managed by Composer, a typical dependency installation command is:
cd "$RELEASE_DIR"
composer install \
--no-dev \
--prefer-dist \
--no-interaction \
--optimize-autoloader
Run this only if Composer is installed and your project includes a valid composer.json file. If your application requires a different PHP version or PHP extensions, verify those requirements before installing dependencies.
For a Node.js project that uses npm and includes a lockfile, you might use:
cd "$RELEASE_DIR"
npm ci
Run the production build command defined by your project, if required. Some applications need a frontend build, while others do not.
For Python applications, dependency installation may involve creating a virtual environment and installing packages from a pinned requirements file.
The important rule is to install dependencies and prepare build artifacts inside the new release directory, not inside the active release. This keeps the currently running application intact while the next version is being prepared.
Do not run every example command for every application. Choose the dependency and build steps that match your actual project.
Step 7: Activate the New Release
Once the new release is ready, update the current symbolic link to point to it.
First, save the path of the existing release if one is active:
cd /var/www/myapp
if [ -L current ]; then
readlink -f current
fi
You can then create a temporary symbolic link and rename it into place:
ln -s "$RELEASE_DIR" /var/www/myapp/current.new
mv -Tf /var/www/myapp/current.new /var/www/myapp/current
Run these commands from the same shell session in which RELEASE_DIR was defined. If you start a new session, set RELEASE_DIR to the actual release path first.
On Linux filesystems that support the operation, replacing the symbolic link this way avoids leaving current pointing to a partially copied directory. It does not guarantee a zero-downtime deployment by itself; application startup, database changes, and web-server configuration still matter.
Configure your web server’s document root or application working directory to use the correct path. For example, a PHP website may serve its public directory from:
/var/www/myapp/current/public
A Node.js or Python application may instead require a systemd service configured to run from /var/www/myapp/current.
Step 8: Configure Permissions Correctly
Incorrect permissions can cause HTTP 403 errors, failed uploads, missing files, or application startup problems.
The deployment account should own the release files it manages. The web server should have only the access required to read the application files and write to explicitly designated runtime directories.
Review ownership and permissions:
ls -ld /var/www/myapp
ls -ld /var/www/myapp/current
ls -la /var/www/myapp/current
Do not solve permission issues by making everything writable:
chmod -R 777 /var/www/myapp
This is unsafe because it grants broad write access to application files and can allow an untrusted process to modify executable code.
Instead, use the correct owner, group, and minimum required permissions. For example, read-only application files and restricted write access to upload or cache directories are usually a better starting point.
Some frameworks need writable cache, session, or storage directories. Give write access only to those specific locations, following the framework’s documentation and your server’s user model.
Step 9: Restart the Application and Verify the Deployment
After activating the new release, perform the actions required by your application.
A Node.js or Python application managed by a systemd service may need a restart:
sudo systemctl restart myapp
sudo systemctl status myapp --no-pager
The deployment user will need an explicitly configured, narrowly scoped authorization to perform these commands. Do not grant unrestricted sudo access merely to make deployment easier.
Inspect the service logs if it fails:
sudo journalctl -u myapp -n 100 --no-pager
For PHP applications served directly by a web server, a service restart may not be required for every code change. Framework caches, PHP OPcache settings, and queue workers may need separate handling.
Finally, test the application through its actual URL or health-check endpoint. Check that the homepage or API responds, database connectivity works, static assets load, and the application logs do not show new errors.
A successful Git clone is not proof that the production deployment succeeded.
Step 10: Roll Back to a Previous Release
One of the main advantages of a release-based Git deployment workflow on a VPS is the ability to restore the previous application code without rebuilding it from scratch.
List available releases:
ls -1 /var/www/myapp/releases
Identify the last known-good release and set its exact directory path:
PREVIOUS_RELEASE="/var/www/myapp/releases/20261111100000"
Confirm that the directory exists and contains the expected application files before proceeding.
Switch the active symbolic link:
ln -s "$PREVIOUS_RELEASE" /var/www/myapp/current.rollback
mv -Tf /var/www/myapp/current.rollback \
/var/www/myapp/current
Then restart the application if necessary and run your health checks again.
This example assumes the previous release is still available and compatible with the current environment. Keep enough releases to support recovery, but remove old releases only after confirming that they are no longer needed.
Important: Rolling back application code does not automatically reverse database migrations or restore deleted user uploads. Use backward-compatible database changes where possible, and maintain tested database backups before risky migrations.
Step 11: Automate the Deployment Workflow
Once manual deployment works reliably, you can automate it with a deployment script or CI/CD platform.
A common approach is to use GitHub Actions, GitLab CI/CD, or another build system to run tests and trigger a deployment on an approved branch or release tag.
A typical automated workflow includes:
- Run tests and code-quality checks.
- Build the application and prepare dependencies.
- Connect to the VPS using a dedicated deployment credential.
- Create a new release directory.
- Install production dependencies and apply approved preparation steps.
- Activate the release.
- Restart services if required.
- Perform health checks and report the result.
Store deployment credentials in the CI/CD platform’s secret-management facility, not in the repository. Use a dedicated SSH key with the minimum necessary permissions, protect production environments, and require approval where appropriate.
Avoid exposing a public deployment endpoint that executes arbitrary shell commands. Restrict inbound SSH access where practical, verify repository changes before release, and ensure the deployment process cannot be used to gain unrestricted root access.
Automation should make a tested deployment process repeatable, not bypass the checks that make it safe.
Common Git Deployment Problems and Their Solutions
Permission denied when accessing the repository
This usually indicates that the server is using the wrong SSH key, the public key has not been authorized, or the repository URL is incorrect.
Check the repository URL and test SSH authentication. Confirm that the deploy key has access to the correct repository.
The website shows an error after deployment
Inspect application and web-server logs, verify environment variables, and confirm that dependencies were installed successfully. Check the service status and compare the active release with the last known-good version.
If necessary, roll back the application code while investigating the cause.
The application cannot read the environment file
Check that the symbolic link points to the intended file and that the application process has permission to read it. Avoid making secrets world-readable to work around the issue.
The deployment works, but old code still appears
Possible causes include application caches, PHP OPcache, long-running workers, a service that was not restarted, or a deployment pointing to the wrong directory. Verify the active symlink and refresh only the caches or services relevant to your application.
The deployment fails during a database migration
Review the migration output and database logs before retrying. Do not assume that a failed migration made no changes. Restore from a verified backup if necessary, and plan migrations so the old and new application versions can coexist during the release transition.
Best Practices for Production VPS Deployments
For a reliable production workflow, follow these principles:
- Deploy tested commits or release tags rather than unreviewed code.
- Keep production credentials outside Git.
- Use a dedicated deployment account and restricted SSH credentials.
- Prepare releases separately before activating them.
- Preserve previous releases for quick code rollback.
- Test database migrations and maintain verified backups.
- Apply the minimum permissions required by each process.
- Monitor service health, application logs, disk space, and deployment failures.
- Test the rollback procedure before relying on it during an outage.
Remember that release-based deployments improve code management, but they do not replace a backup strategy. Your application files, database, uploaded content, and configuration may require separate recovery procedures.
A well-designed Git deployment workflow makes managing a production application on a Linux VPS more predictable and easier to maintain. By combining repository-based version control, SSH authentication, a dedicated deployment user, external environment configuration, release directories, and a tested rollback procedure, you can reduce deployment mistakes and recover from code-related failures more efficiently.
Start with a manual deployment process, verify every step, and automate it only after the workflow is stable. As your application grows, you can add automated tests, build pipelines, health checks, release approvals, and monitoring.
