Skip to content

README.md

Latest commit

 

History

History
231 lines (166 loc) · 8.18 KB

README.md

File metadata and controls

231 lines (166 loc) · 8.18 KB


codeware sthlm logo

Nx Fly Deployment Action

GitHub action that brings automatic Fly.io deployments to your Nx workspace.

@cdwr/nx-fly-deployment-action npm   MIT

Description

This action will manage deployments to Fly.io of your Nx workspace applications.

Fits perfectly with Nx Pre-deploy Action for multi-tenant setups.

[!NOTE] Architecture, multi-tenant setup, and configuration See: DEPLOYMENT.md

Required Application Setup

Each deployable app requires:

  1. github.json - Deployment configuration in app root (optional postgres settings)
  2. Fly.io configuration - One of the following:
    • fly.{environment}.toml (e.g., fly.production.toml, fly.preview.toml)
    • fly.toml (default)
    • For existing apps: remote configuration will be automatically fetched and used

Fly Configuration Selection Logic

During deployment, the action uses this priority order:

  1. Existing apps: Saves and uses remote configuration from Fly.io
  2. New apps: Looks for environment-specific config (e.g., fly.production.toml)
  3. New apps: Falls back to fly.toml
  4. No config found: Deployment is skipped

Tip

To disable deployment for an app, remove or rename its Fly configuration file (e.g., rename to fly.local.toml for manual deployments).

Applications without a github.json file will be skipped during deployment.

[!NOTE] github.json schema, field descriptions, and examples See: Per-App Configuration in DEPLOYMENT.md

Usage

Important

Using the action is currently limited to cloning this repository since the package isn't deployed according to action best practices.

We have a monorepo and are considering other options to make the action available to other repositories.

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

# Install dependencies and tools...
# Build packages...

# Fly CLI must be installed
- name: Install Fly CLI
  uses: superfly/flyctl-actions/setup-flyctl@master
  with:
    version: 0.3.45

# Let Nx analyze which projects are affected and hence will be deployed
- name: Analyze affected projects to deploy
  uses: nrwl/nx-set-shas@v4
  with:
    set-environment-variables-for-job: true

- name: Run Nx Fly Deployment
  uses: ./packages/nx-fly-deployment-action
  with:
    fly-api-token: ${{ secrets.FLY_API_TOKEN }}
    token: ${{ secrets.GITHUB_TOKEN }}

Environment Determination

Environment is determined by the GitHub event:

  • Pull requests → preview
  • Push to main → production

Environment variables provided to deployed apps: DEPLOY_ENV, APP_NAME, PR_NUMBER, TENANT_ID

[!NOTE] Environment detection logic and affected apps analysis

See: Nx Pre-deploy Action

Inputs

See action.yaml for descriptions of the inputs.

Additional input details

app-details

Provide a JSON object that maps app names to their deployment configurations. This supports both multi-tenant deployments and multi-deployment scenarios (e.g., multiple environments). This is typically the output from the Nx Pre-deploy Action.

[!NOTE] Setting up multi-tenant configuration in Infisical See: Multi-tenant Setup Guide

Structure:

{
  "web": [
    {
      "tenant": "acme",
      "env": { "PUBLIC_URL": "https://acme.example.com" },
      "secrets": { "API_KEY": "sk_acme_..." }
    },
    {
      "tenant": "globex",
      "env": { "PUBLIC_URL": "https://globex.example.com" },
      "secrets": { "API_KEY": "sk_globex_..." }
    }
  ],
  "cms": [{ "tenant": "acme" }]
}

Behavior:

  • Each app is deployed once per deployment configuration
  • Apps get unique names: <base-app-name>-<tenant-id> (e.g., cdwr-web-acme, cdwr-web-globex)
  • The TENANT_ID environment variable is set for each deployment
  • Config merging: Global env/secrets are merged with deployment-specific config (deployment wins)
  • If no app-tenants provided, apps deploy once with only global config

Example usage:

- name: Deploy
  uses: ./packages/nx-fly-deployment-action
  with:
    app-details: ${{ needs.pre-deploy.outputs.app-tenants }}
    env: |
      GLOBAL_VAR=shared-value
    secrets: |
      SHARED_SECRET=xyz

In this example, GLOBAL_VAR and SHARED_SECRET are available to all deployments, but deployment-specific values take precedence if they have the same key.

Note: The tenant field is optional. You can provide env/secrets without a tenant for multi-deployment scenarios (e.g., different configurations for staging/production).

postgres-preview

When a Fly Postgres cluster has been created, you can attach the application to a postgres database automatically on deployment to the preview environment.

Provide the name of the postgres application. Fly will provide DATABASE_URL as a secret to the application to be able to connect to the database.

Before the application gets destroyed, the Postgres cluster will detach the application from the database.

Database Name Sharing: By default, Fly creates a unique database for each attached app (e.g., myapp-pr-123, myapp-pr-123-tenant). To ensure multiple apps share the same database, specify flyPostgresDatabaseName in your github.json:

{
  "flyPostgresPreview": "${POSTGRES_PREVIEW}",
  "flyPostgresDatabaseName": "shared_db_name"
}

This is essential for multi-tenant architectures where a platform host manages the database schema and tenant apps need access to the same data.

Read more about attach or detach a Fly app.

secrets

Global secrets passed to all deployed applications as Fly secrets. These are merged with deployment-specific secrets from app-details (deployment-specific takes precedence).

Provide the secrets as multiline key/value strings.

- uses: ./packages/nx-fly-deployment-action
  with:
    secrets: |
      SECRET_KEY1=secret-value1
      SECRET_KEY2=secret-value2

Note

The same pattern also applies to env and build-args inputs.

build-args

Global build arguments passed to Docker during image build (via --build-arg). These are available during the build phase but not at runtime. Use this for client-side environment variables (e.g., NEXT_PUBLIC_*) that need to be embedded in the bundle.

Important

You must declare each build arg in your Dockerfile with ARG directives. Keep them as ARG only (don't convert to ENV) to avoid persisting secret values in the final Docker image.

Runtime values are provided separately via env and secrets.

# Dockerfile - ARG only for security
ARG NEXT_PUBLIC_API_URL
ARG NEXT_PUBLIC_DEPLOY_ENV
ARG SENTRY_AUTH_TOKEN

RUN npm run build

When to use:

  • Client-side environment variables (NEXT_PUBLIC_* in Next.js)
  • Build-time configuration that needs to be embedded in the application bundle
  • Source map upload tokens (e.g. SENTRY_AUTH_TOKEN)

When NOT to use:

  • Runtime secrets (use secrets input instead)
  • Server-side only environment variables (use env input instead)

Outputs

See action.yaml for descriptions of the outputs.