Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

Pre-Requisites

Complete these first:

Deploy Application at least once locally
AWS credentials configured for your CI environment

Introduction

The Fjall CLI runs in CI/CD pipelines without extra configuration. When it detects a non-interactive environment (no TTY), it switches to plain text output and returns standard exit codes. Official plugins cover GitHub Actions and Buildkite. For any other CI system, install and invoke the CLI directly.

GitHub Actions

The fjall-io/fjall-deploy-action is a composite action that installs the CLI and runs it with the right flags.

Minimal Workflow

name: Deploy
on:
  push:
    branches: [main]

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

      - uses: fjall-io/fjall-deploy-action@v1
        with:
          target: api
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_REGION: us-east-2

With AWS OIDC (Recommended)

Use GitHub’s OIDC provider for keyless authentication. No long-lived secrets to rotate:

name: Deploy
on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

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

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/deploy
          aws-region: us-east-2

      - uses: fjall-io/fjall-deploy-action@v1
        with:
          target: api
          verbose: true

With Fjall OIDC

If your app is registered with Fjall, the CLI auto-detects GitHub’s OIDC tokens. Just grant id-token: write and set your API key:

permissions:
  id-token: write
  contents: read

steps:
  - uses: actions/checkout@v4
  - uses: fjall-io/fjall-deploy-action@v1
    with:
      target: api
    env:
      FJALL_API_KEY: ${{ secrets.FJALL_API_KEY }}

Split Infrastructure and Code Deploys

Run infrastructure changes and code deploys as separate jobs for faster iteration:

jobs:
  infra:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/deploy
          aws-region: us-east-2
      - uses: fjall-io/fjall-deploy-action@v1
        with:
          target: api
          mode: infra-only

  code:
    needs: infra
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/deploy
          aws-region: us-east-2
      - uses: fjall-io/fjall-deploy-action@v1
        with:
          target: api
          mode: deploy-only

Action Inputs

Input	Required	Default	Description
`command`	no	`deploy`	`deploy`, `destroy`, or `build`
`target`	yes	—	App name, `organisation`, `platform`, or `account`
`service`	no	—	Specific ECS service name
`mode`	no	`full`	`full`, `infra-only`, or `deploy-only`
`environment`	no	—	Free-form CI/CD label passed to CDK synthesis
`verbose`	no	`false`	Enable verbose logging
`skip-build`	no	`false`	Skip Docker build
`no-cascade`	no	`false`	Skip cascade after organisation deploy
`cli-version`	no	`latest`	Pin `fjall` version
`working-directory`	no	`.`	Directory containing `fjall-config.json`
`force`	no	`false`	Force flag for destroy

The environment input is a free-form label for your own CI/CD logic. It does not select an AWS account or region. The deploy account is chosen by the active deployment target (fjall target set), and the region by your AWS credentials or the region setting.

Buildkite

The fjall-io/fjall-deploy-buildkite-plugin installs the CLI and runs it with the right flags.

Minimal Pipeline

steps:
  - label: ":rocket: Deploy"
    plugins:
      - fjall-io/fjall-deploy#v1.0.0:
          target: api

With AWS OIDC

steps:
  - label: ":rocket: Deploy"
    plugins:
      - aws-assume-role-with-web-identity#v1.0.0:
          role-arn: arn:aws:iam::123456789012:role/deploy
      - fjall-io/fjall-deploy#v1.0.0:
          target: api

Staging to Production Pipeline

steps:
  - label: ":test_tube: Staging"
    plugins:
      - fjall-io/fjall-deploy#v1.0.0:
          target: api
          environment: staging

  - wait

  - block: ":raised_hand: Deploy to Production?"

  - label: ":rocket: Production"
    plugins:
      - fjall-io/fjall-deploy#v1.0.0:
          target: api
          environment: production
          skip-build: true

Plugin Properties

Property	Required	Default	Description
`command`	no	`deploy`	`deploy`, `destroy`, or `build`
`target`	yes	—	App name, `organisation`, `platform`, or `account`
`service`	no	—	Specific ECS service name
`mode`	no	`full`	`full`, `infra-only`, or `deploy-only`
`environment`	no	—	Free-form CI/CD label passed to CDK synthesis
`verbose`	no	`false`	Enable verbose logging
`skip-build`	no	`false`	Skip Docker build
`no-cascade`	no	`false`	Skip cascade after organisation deploy
`cli-version`	no	`latest`	Pin `fjall` version
`working-directory`	no	`.`	Directory containing `fjall-config.json`
`force`	no	`false`	Force flag for destroy

Raw CLI Usage (Any CI System)

If you’re using a different CI system (GitLab CI, CircleCI, Jenkins, etc.), install and invoke the CLI directly.

Setup

# Install Node.js 22+ and the CLI
npm install -g @fjall/cli

# Deploy
fjall deploy api --non-interactive --skip-confirmation

The --non-interactive flag switches to plain text output. The --skip-confirmation flag suppresses interactive confirmation prompts. Both are essential for CI.

Key Flags

Flag	Description
`--non-interactive`	Plain text output (no TUI)
`--skip-confirmation`	Skip confirmation prompts
`--infra-only`	Deploy only infrastructure
`--deploy-only`	Deploy only code
`--skip-build`	Skip Docker build (use with `--deploy-only`)
`--skip-migrations`	Skip database migrations during this deployment
`-v, --verbose`	Enable verbose logging
`-e, --environment <env>`	Free-form CI/CD label passed to CDK synthesis (not an account selector)
`--target <name>`	Override the active deployment target for this deploy
`--region <region>`	Deploy to a specific region within the target’s account
`--no-cascade`	Skip cascade for organisation deploys
`-f, --force`	Redeploy all stacks even when no changes are detected

Exit Codes

Code	Meaning
`0`	Success
`1`	Failure
`130`	Interrupted (SIGINT)

Environment Variables

Variable	Description
`FJALL_API_KEY`	API key for Fjall OIDC authentication
`AWS_ACCESS_KEY_ID`	AWS access key
`AWS_SECRET_ACCESS_KEY`	AWS secret key
`AWS_REGION`	AWS region
`AWS_SESSION_TOKEN`	Temporary session token (if using STS)

Example: GitLab CI

deploy:
  image: node:22
  script:
    - npm install -g @fjall/cli
    - fjall deploy api --non-interactive --skip-confirmation --verbose
  only:
    - main

Example: CircleCI

jobs:
  deploy:
    docker:
      - image: cimg/node:22.0
    steps:
      - checkout
      - run: npm install -g @fjall/cli
      - run: fjall deploy api --non-interactive --skip-confirmation --verbose

Setting Up AWS Credentials

Whichever CI system you use, the Fjall CLI needs AWS credentials to deploy. Here are the common approaches, from most to least recommended:

OIDC (Recommended)

Most CI systems support OIDC federation with AWS. This avoids storing long-lived secrets:

Create an IAM OIDC identity provider for your CI system
Create an IAM role with a trust policy scoped to your repo/pipeline
Use your CI’s OIDC integration to assume that role

Static Credentials

Store AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as CI secrets. Simpler to set up but requires key rotation.

Instance Profiles

When your CI agents run on EC2 (for example, self-hosted Buildkite agents), attach an IAM instance profile with the required permissions. No credential management needed.

Next Steps

Deploy an Application

Run a full deploy locally before wiring it into CI/CD.

deploy Command Reference

Every fjall deploy flag, target, and option.

Understanding Profiles

How Fjall derives AWS profiles and selects the deploy target.

Configure a Deployment User

Scope the IAM role your pipeline assumes.

​Introduction

​GitHub Actions

​Minimal Workflow

​With AWS OIDC (Recommended)

​With Fjall OIDC

​Split Infrastructure and Code Deploys

​Action Inputs

​Buildkite

​Minimal Pipeline

​With AWS OIDC

​Staging to Production Pipeline

​Plugin Properties

​Raw CLI Usage (Any CI System)

​Setup

​Key Flags

​Exit Codes

​Environment Variables

​Example: GitLab CI

​Example: CircleCI

​Setting Up AWS Credentials

​OIDC (Recommended)

​Static Credentials

​Instance Profiles

​Next Steps

Deploy an Application

deploy Command Reference

Understanding Profiles

Configure a Deployment User

Introduction

GitHub Actions

Minimal Workflow

With AWS OIDC (Recommended)

With Fjall OIDC

Split Infrastructure and Code Deploys

Action Inputs

Buildkite

Minimal Pipeline

With AWS OIDC

Staging to Production Pipeline

Plugin Properties

Raw CLI Usage (Any CI System)

Setup

Key Flags

Exit Codes

Environment Variables

Example: GitLab CI

Example: CircleCI

Setting Up AWS Credentials

OIDC (Recommended)

Static Credentials

Instance Profiles

Next Steps