blackhost/deployer repository overview

⁠🚀 DEP 9000

Deployer 9000 is a small Alpine-based image that syncs a directory to a remote server over FTP / FTPS, SFTP or rsync over SSH, with optional commands before and after the transfer. It was built for GitHub Actions⁠ and runs anywhere where a container can reach your server: GitLab CI, a cron job, your laptop.

Unlike its infamous cousin HAL, this unit has one mission: get your code deployed, no backtalk.

• Protocols: FTP, FTPS with TLS verification, SFTP, rsync over SSH
• Configured by environment variables, nothing else to mount or install
• Pre/post deploy commands on the remote host over SSH
• Delta uploads: with PRESERVE_TIMES only the files that changed are uploaded, nothing is stored on the server
• Safe by default: dotfiles stay off the server, a deploy that would wipe the target is refused, SSH host keys can be pinned
• Dry run that logs in and shows what would change
• Minimal: Alpine, lftp, rsync, OpenSSH client, git, bash

⁠Quick start: GitLab CI

deploy:
  image: blackhost/deployer:1
  stage: deploy
  script: [deployer]
  variables:
    PROTOCOL: sftp
    SERVER: example.com
    REMOTE_DIR: public_html
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Add USERNAME and PASSWORD (or SSH_KEY) as masked CI/CD variables in Settings → CI/CD → Variables. The job runs inside your checked-out repository, so LOCAL_DIR defaults to the project root.

Two jobs for two targets is just two variables: blocks:

deploy-api:
  extends: deploy
  variables: { SERVER: api.example.com, PASSWORD: *** }
  rules: [{ if: $CI_COMMIT_BRANCH == "api" }]

Keep deploy settings inside the job. Project-wide variables with the same names (PORT, DRY_RUN, DELETE, PARALLEL) are picked up too.

⁠Quick start: docker run

docker run --rm -v "$PWD:/deploy" \
  -e PROTOCOL=sftp -e SERVER=example.com -e REMOTE_DIR=public_html \
  -e USERNAME=deploy -e PASSWORD="***" \
  blackhost/deployer:1

The image's working directory is /deploy. Mount the folder you want to ship there, or set LOCAL_DIR. Add -e DRY_RUN=true to see the plan first.

⁠Quick start: GitHub Actions

Use the action instead of the image directly, inputs map one to one to the variables below:

- uses: Black-HOST/deployer@v1
  with:
    server: ${{ secrets.FTP_HOST }}
    username: ${{ secrets.FTP_USER }}
    password: *** secrets.FTP_PASS }}
    remote_dir: public_html

Full documentation at https://github.com/Black-HOST/deployer⁠.

⁠Configuration

Every option is an environment variable. GitHub Actions users write the same names in lowercase under with:.

Boolean values accept true, false, yes, no, 1, 0, on, off.

⁠Behaviour worth knowing

• A deploy makes the server match the source. A CI job starts from a fresh checkout, so without PRESERVE_TIMES every file looks new and FTP and SFTP upload all of them. Set PRESERVE_TIMES=true in a git checkout to upload only what changed; shallow checkouts are completed automatically.
• Uploads replace files atomically. Over FTP and SFTP a file is uploaded under a temporary name and renamed when complete, so a changed file is never missing during a deploy.
• DELETE=true removes files. Anything under REMOTE_DIR that is not in LOCAL_DIR and not excluded is deleted, and that covers dotfiles you list in INCLUDE. Run with DRY_RUN=true first, every time you change the exclude list. With nothing to deploy the job is refused, unless SAFEGUARDS=false.
• Dry runs fail like real runs. Wrong host, port, TLS or credentials exit non-zero, so a dry-run job on merge requests is a real check.
• Host keys are accepted on first connection, trust on first use. Set HOST_KEY to trust one key only and refuse everything else.
• Exit code is non-zero whenever a transfer, a pre or post script, or a login fails. Your pipeline sees it.

⁠Tags

Images are built from tagged releases of the GitHub repository and are also published on ghcr.io/black-host/deployer.

⁠Links

• Source, issues and GitHub Action: https://github.com/Black-HOST/deployer⁠
• GitHub Marketplace: https://github.com/marketplace/actions/deployer-9000⁠
• License: MIT
• Made by Black HOST⁠