FTL Deploy Action

Deploy applications using FTL (Faster Than Light) from GitHub Actions workflows.

Features

• 🚀 Zero-downtime deployments with health checks
• 🔒 Secure SSH-based deployment from GitHub runners
• 🐳 Docker-based deployment with layer optimization
• 🌐 Automatic SSL/TLS certificate management
• 📦 Optional server setup for first-time deployments
• ♻️ Configurable build and deploy workflows

Prerequisites

1. FTL Configuration: Your repository must contain ftl.yaml configuration file
2. SSH Access: SSH private key for target server stored in GitHub Secrets
3. Server Requirements: Target server must meet FTL server requirements
4. Domain: Domain name pointing to your server (for SSL certificates)

Quick Start

Basic Usage

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Deploy with FTL
        uses: yarlson/ftl-deploy-action@v1
        with:
          ssh-key: ${{ secrets.SSH_PRIVATE_KEY }}

With Environment Variables

- name: Deploy with FTL
  uses: yarlson/ftl-deploy-action@v1
  with:
    ssh-key: ${{ secrets.SSH_PRIVATE_KEY }}
  env:
    REDIS_PASSWORD: ${{ secrets.REDIS_PASSWORD }}
    DATABASE_URL: ${{ secrets.DATABASE_URL }}
    API_KEY: ${{ secrets.API_KEY }}

Inputs

Input	Description	Required	Default
ssh-key	SSH private key for server access	Yes	-
ftl-version	FTL version to install	No	latest
working-directory	Directory containing ftl.yaml	No	.
run-setup	Run ftl setup before deploy	No	false
run-build	Run ftl build before deploy	No	true
skip-push	Skip pushing to registry (--skip-push flag)	No	false

Advanced Usage

First-Time Server Setup

For initial deployment to a new server, enable run-setup:

- name: Initial Server Setup and Deploy
  uses: yarlson/ftl-deploy-action@v1
  with:
    ssh-key: ${{ secrets.SSH_PRIVATE_KEY }}
    run-setup: 'true'

This will:

• Install Docker and system dependencies
• Configure firewall rules
• Set up Docker networks
• Initialize the server for FTL deployments

Pin to Specific FTL Version

- name: Deploy with FTL v1.2.3
  uses: yarlson/ftl-deploy-action@v1
  with:
    ssh-key: ${{ secrets.SSH_PRIVATE_KEY }}
    ftl-version: 'v1.2.3'

Separate Build and Deploy Jobs

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build Docker images
        uses: yarlson/ftl-deploy-action@v1
        with:
          ssh-key: ${{ secrets.SSH_PRIVATE_KEY }}
          run-build: 'true'
          skip-push: 'false'

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to server
        uses: yarlson/ftl-deploy-action@v1
        with:
          ssh-key: ${{ secrets.SSH_PRIVATE_KEY }}
          run-build: 'false'

Monorepo Support

- name: Deploy API Service
  uses: yarlson/ftl-deploy-action@v1
  with:
    ssh-key: ${{ secrets.SSH_PRIVATE_KEY }}
    working-directory: ./services/api

- name: Deploy Web Service
  uses: yarlson/ftl-deploy-action@v1
  with:
    ssh-key: ${{ secrets.SSH_PRIVATE_KEY }}
    working-directory: ./services/web

Skip Registry Push (Direct SSH Transfer)

If using FTL's direct SSH transfer mode (no registry):

- name: Deploy without registry
  uses: yarlson/ftl-deploy-action@v1
  with:
    ssh-key: ${{ secrets.SSH_PRIVATE_KEY }}
    skip-push: 'true'

Setting Up SSH Key

1. Generate SSH Key Pair (if you don't have one):

   ssh-keygen -t ed25519 -C "github-actions-deploy" -f ~/.ssh/ftl_deploy

2. Add Public Key to Server:

   ssh-copy-id -i ~/.ssh/ftl_deploy.pub user@your-server.com

3. Add Private Key to GitHub Secrets:

   • Go to your repository → Settings → Secrets and variables → Actions
   • Click "New repository secret"
   • Name: SSH_PRIVATE_KEY
   • Value: Contents of ~/.ssh/ftl_deploy (entire file including BEGIN/END markers)

Environment Variables

FTL supports environment variable substitution in ftl.yaml:

# ftl.yaml
dependencies:
  - name: postgres
    env:
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_USER=${DB_USER:-postgres}

Pass variables in your workflow:

- uses: yarlson/ftl-deploy-action@v1
  with:
    ssh-key: ${{ secrets.SSH_PRIVATE_KEY }}
  env:
    DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
    DB_USER: ${{ secrets.DB_USER }}

Troubleshooting

SSH Authentication Fails

Error: Permission denied (publickey)

Solutions:

• Verify SSH private key is complete (including -----BEGIN and -----END markers)
• Ensure public key is in ~/.ssh/authorized_keys on target server
• Check server user has correct permissions: chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys

FTL Configuration Validation Error

Error: Error: ftl.yaml not found

Solutions:

• Ensure ftl.yaml exists in repository root
• If in subdirectory, set working-directory input
• Verify file is committed to repository

Build Fails

Error: failed to build image

Solutions:

• Check Dockerfile exists at path specified in ftl.yaml
• Verify Docker build context is correct
• Check GitHub Actions logs for specific build errors

Server Connection Timeout

Error: connection timeout or no route to host

Solutions:

• Verify server IP/hostname is correct in ftl.yaml
• Ensure server firewall allows SSH (port 22) from GitHub Actions IPs
• Check server is running and accessible

Example Repository

See ftl-examples for complete example projects with GitHub Actions workflows.

Related Resources

• FTL Documentation
• FTL GitHub Repository
• GitHub Actions Documentation

License

MIT License - see LICENSE for details.

Support

• Issues: GitHub Issues
• Documentation: ftl-deploy.org
• Community: GitHub Discussions