How It Works

Pushdeck deploys your application by cloning a fresh copy of your repository, running your custom scripts, then switching your web server to the new release in one instant step. Your visitors never see partially-deployed code.

# What your server looks like after a few deployments:
/var/www/myapp/
├── releases/
│   ├── 20260401120000/     # old release (kept for rollback)
│   ├── 20260402090000/     # older release
│   └── 20260402160000/     # ← newest release
├── .env                    # shared, never inside a release
└── current -> releases/20260402160000/  # symlink your web server points to

Deployment Pipeline

Every deployment runs the following steps in strict sequence. If any step fails, the deployment stops and your live release is left untouched.

Hook ordering

Go to the Hooks tab and drag your hooks into the position you want. Hooks above Activate New Release run before the new release goes live; hooks below run after.

What You Need Before Starting

1. Create a Project

Log in and click New Project from the dashboard.

2. Add Your Server

Pushdeck generates a unique SSH key pair for each server you add. You get a public key to place on your server. You never share any of your own private keys with Pushdeck. You stay in full control: remove the key from your server at any time and Pushdeck can no longer connect.

Step 1: Add the server in Pushdeck

On your project overview, click Add Server and fill in the details:

Click Generate Key & Continue. Pushdeck creates the key pair and takes you to the server page where the public key is waiting for you.

Step 2: Add Pushdeck's public key to your server

Copy the public key shown on the server page. Then SSH into your server as the same user you entered in step 1 and run:

# Make sure the .ssh directory exists
mkdir -p ~/.ssh && chmod 700 ~/.ssh

# Open (or create) the authorized_keys file, paste the key on a new line, then save
nano ~/.ssh/authorized_keys

# Set the correct permissions
chmod 600 ~/.ssh/authorized_keys

# Make sure your user has write access to the deploy path
sudo chown -R ubuntu:ubuntu /var/www/your-app

Replace ubuntu and /var/www/your-app with your actual username and deploy path. If you are using a separate deployment user, SSH as that user instead and follow the same steps.

Step 3: Test the connection

Back in Pushdeck, click Test Connection on the project overview. You need a green connected badge before you can deploy.

3. Connect Your Repository

Click the Repository tab on your project, then Connect Repository.

Pushdeck uses your token only to clone the repository during deployments. We recommend using the most scoped token your provider supports so only that one repository is accessible, nothing else on your account.

GitHub

GitHub offers two types of tokens. We recommend the fine-grained token as it can be locked to a single repository with read-only access.

GitLab

For GitLab, use a project access token rather than a personal access token. It is scoped to a single project and does not touch anything else on your account.

4. Deployment Hooks

Hooks are shell scripts that run on your servers during every deployment. Go to the Hooks tab and click Add Hook.

Hook fields

After saving, drag the hook in the pipeline table to set when it runs. Drop it above Activate New Release to run before the new release goes live, or below to run after.

Laravel / PHP

Place these hooks above Activate so they run before the new release goes live:

# Install Composer dependencies (no dev packages)
composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader

# Run database migrations
php artisan migrate --force

# Cache config, routes, and views for production
php artisan config:cache
php artisan route:cache
php artisan view:cache

Place these hooks below Activate so they run after the new release is live:

# Restart the queue worker
php artisan queue:restart

# Reload PHP-FPM (use your actual service name)
sudo systemctl reload php8.3-fpm

Node.js

# Install production dependencies
npm ci --omit=dev

# Build assets (if applicable)
npm run build

# After activate: reload with PM2
pm2 reload ecosystem.config.js --env production

Python / Django

Place these hooks above Activate so the release is ready before it goes live:

# Install dependencies
pip install -r requirements.txt

# Run database migrations (Django)
python manage.py migrate --noinput

# Collect static files (Django)
python manage.py collectstatic --noinput

# After activate: restart the app service (gunicorn, uvicorn, etc.)
sudo systemctl restart gunicorn

Generic

# Any shell commands work; they run from the release directory
bundle install --without development test
bundle exec rake assets:precompile

5. Linked Folders

Every deployment clones a fresh copy of your repository into a new release folder. That means anything generated at runtime (user uploads, logs, cache files) would be lost on the next deploy unless you tell Pushdeck to preserve it.

Linked Folders solve this. You define folder paths relative to your project root, and on every deploy Pushdeck:

1. Creates the folder inside {deploy_path}/shared/ if it does not already exist.
2. Removes that folder from the freshly cloned release.
3. Creates a symlink from the release folder to the shared copy.

The result is that all releases point at the same physical folder on disk, so data accumulates across deployments instead of disappearing.

Where to configure

Go to the Hooks tab and click the Linked Folders button in the top right. Add one path per input field, then click Save.

Folder structure on the server

Given a deploy path of /var/www/myapp and a linked folder of storage, your server looks like this:

/var/www/myapp/
  shared/
    storage/              # real folder, never deleted
  releases/
    20260404120000/
      storage             # symlink to ../../shared/storage
    20260403110000/
      storage             # symlink to ../../shared/storage
  current                 # symlink to latest release

Laravel

Laravel generates files at runtime that must survive deployments. Add these two paths:

Only needed if your app stores uploaded files on the local disk (not S3 or cloud storage). If so, add this as a hook below Activate:

php artisan storage:link

This creates a public/storage link so files saved to storage/app/public are accessible in the browser. It is safe to run on every deploy as it does nothing if the link already exists.

Other stacks

6. Environment Variables

Click the Environment tab to store your .env file contents securely. On each deployment, Pushdeck automatically links this file into the release as .env so you never have to copy it manually. For a Laravel app, paste the full contents of your production .env here, including APP_KEY, database credentials, and any third-party API keys.

Your First Deploy

Before deploying, confirm:

• All servers show a connected badge (click Test on each server).
• A repository is connected.
• Your environment file is saved under the Environment tab. Pushdeck writes it to your server automatically when you save. For a Laravel app, make sure APP_KEY is set before your first deploy.

Click Deploy Now from the project overview, the Deployments tab, or the dashboard. The deployment runs in the background and you will be taken to the deployment detail page where each pipeline step updates in real time.

Reading the Logs

The deployment detail page shows the pipeline as a table of steps. Each row is one step on one server.

When a step fails, all remaining steps are immediately marked as failed so you can see the full picture right away. Steps that ran successfully before the failure keep their output and timestamps. Click the eye icon to inspect them.

Rolling Back

Go to the Deployments tab. Any deployment with a success status that is not the current active release will show a Rollback button.

Clicking Rollback re-runs only the Activate step (and any hooks positioned below it) against the selected release without re-cloning. The old release folder is already on disk, so the switch is nearly instant.

CI/CD Webhook

Trigger a deployment automatically from GitHub Actions, GitLab CI, or any HTTP client by hitting your project's Deploy Hook URL. Find it on the project overview under Deploy Hook URL.

# Trigger a deploy with curl (POST)
curl -X POST https://yourpushdeck.com/deploy/YOUR_TOKEN

GitHub Actions example

- name: Deploy
  run: curl -X POST ${{ secrets.PUSHDECK_DEPLOY_URL }}

Notifications

Open the Notifications tab on your project to be told when a deployment finishes. Two channels are available and you can use either or both.

Slack

Connect a Slack Incoming Webhook and Pushdeck posts a message to your chosen channel on every success or failure, with the commit, who triggered it, and the duration.

Webhook (custom integrations)

Point the Notification URL at any endpoint and Pushdeck sends an HTTP POST with a JSON body each time a deployment reaches a final state. The request carries the header User-Agent: Pushdeck-Webhook/1.0.

Events (the event field):

• deployment.completed — a deployment finished. Read status for success or failed.
• test — sent only when you click "Send a test notification".

Example payload:

{
  "event": "deployment.completed",
  "status": "success",                  // or "failed"
  "deployment": {
    "id": 123,
    "release": "20260402070456",
    "status": "success",
    "is_rollback": false,
    "started_at": "2026-04-02T07:04:38+00:00",
    "finished_at": "2026-04-02T07:04:56+00:00",
    "duration_seconds": 18,             // null if unknown
    "failure_reason": null,             // set when status is "failed"
    "failure_category": null,           // repository | server | hook | general
    "url": "https://app.pushdeck.dev/projects/1/deployments/123"
  },
  "commit": {
    "hash": "abc1234fde...",            // null if not captured
    "short_hash": "abc1234f",
    "message": "Fix login",
    "author": "Jane",
    "url": "https://github.com/owner/repo/commit/abc1234f"
  },
  "project": {
    "id": 1,
    "name": "My App",
    "repository": "owner/repo",
    "branch": "main"
  },
  "triggered_by": { "name": "Jane" }, // null for webhook/CI deploys
  "timestamp": "2026-04-02T07:04:56+00:00"
}

Team & Roles

Invite teammates to collaborate on a project from the Team tab (visible to the project owner). Access is scoped per project: someone can be an admin on one project and view-only on another.

Roles

Beyond the role, you can fine-tune individual permissions per person (for example, grant a viewer the ability to manage hooks, or revoke notification access from someone who otherwise has it by default). Permissions can be set at invite time and changed later.

Invitations

Security

• SSH keys are generated by Pushdeck. You never share your own private keys. The private key is stored encrypted in the database and decrypted in memory only when a deployment job runs. The public key on your server can be deleted at any time to revoke access.
• Repository access tokens are stored and used only for git clone operations. They are redacted from all log output.
• Environment files are encrypted at rest and require your password to view or edit.
• Deploy Hook URLs contain a random token. Regenerate from the project overview if one gets compromised. They are only shown to the owner and admins.
• Team access is role-based and scoped per project. Members only see what their role and permissions allow; secrets such as the environment file and deploy hook URL are hidden from those without access.
• Deployment jobs run with the same OS user as your SSH connection. Use Run As on hooks to run specific commands as a different user (e.g. www-data) via passwordless sudo.

Troubleshooting

Server shows "failed" after connection test

• Verify the host/IP and port are reachable (nc -zv HOST PORT).
• Confirm you added Pushdeck's public key to ~/.ssh/authorized_keys on the server for the correct user.
• Check that the username in Pushdeck matches the user you added the key for.
• Check that the user has read/write access to the deploy path: ls -la /var/www/myapp. If not, run sudo chown -R your-user:your-user /var/www/myapp.

Clone step fails

• Authentication failed: your access token is invalid or expired. Update it under the Repository tab.
• Repository not found: check the owner/repo spelling and that the token has read access.
• Branch not found: verify the branch name exactly (it is case-sensitive).
• Could not resolve host: the server has no internet access or DNS is not working.
• git: command not found: install git on the server with sudo apt install git.
• Permission denied: the SSH user does not have write access to the deploy path.

Hook step fails

• Click the eye icon on that step to see the full SSH output and exact error.
• All hook commands run from the release directory, so use relative paths.
• If using Run As, the connecting user needs passwordless sudo configured for that target user.
• Test your script manually by SSHing into the server and running it in the release directory.

Deploy button is disabled

• All servers must show a connected badge. Click Test on each server.
• A repository must be connected under the Repository tab.
• A deployment may already be in progress. Wait for it to finish or fail.

A deployment step keeps failing

Pushdeck automates what you would do manually on your server. If a step fails, a good first check is to try the same thing yourself: SSH into the server, navigate to the same directory, and run the same command with the same user. If it fails there too, the issue is with the server configuration, not Pushdeck.

Common things to verify:

• Access tokens (GitHub/GitLab) are valid and have not expired. Update them under the Repository tab.
• The SSH user has the permissions needed to run the commands in your hooks.
• Any external services your scripts call (package registries, databases) are reachable from the server.

If the same command works fine when you run it manually on the server but keeps failing through Pushdeck, open a Help request and share the step output. We are happy to help.