Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

Pre-Requisites

Complete these first:

Deploy Application at least once locally
A CI deploy token (minted in the web app under Settings → CI/CD Tokens), or 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. Pipelines authenticate with a CI deploy token (see below). The token doubles as the pipeline’s AWS credential: the CLI exchanges it for short-lived, deploy-scoped AWS credentials in your connected account, so you don’t need to store AWS keys in CI at all.

CI Deploy Tokens

Fjall issues three kinds of token. Only one belongs in a pipeline:

Prefix	Type	Created with	Use in CI/CD?
`fjall_dk_`	CI deploy token	Settings → CI/CD Tokens (web app)	Yes. Built for pipelines
`fjall_ak_`	Agent token	`fjall token create` or Settings → Scoped Tokens	No. For AI agents and automation with custom scopes
`fj_`	Legacy user key	Settings → API Keys	No. Deprecated for automation

A CI deploy token carries a fixed, least-privilege scope set: read, deploy, and deploy:oidc:mint. That is enough to run deploys and mint short-lived AWS sessions, and nothing more — it cannot manage team members, tokens, or organisation settings. The scopes are stamped at creation and cannot be widened. Deploy tokens expire within 90 days. The cap is enforced by the web-app mint form and by the API, which rejects a longer expiry regardless of client. Rotate before expiry by minting a replacement and updating your CI secret.

Minting and Managing Tokens

Minting a deploy token is admin-equivalent (it grants the org-wide AWS deploy path), so it requires an interactive browser session: an owner or admin mints it in the web app under Settings → CI/CD Tokens, optionally restricted to one application or environment. The token is shown once — store it as a CI secret immediately. API-key-authenticated callers, including the CLI itself, cannot mint deploy tokens. Everything after the mint works from the CLI:

# List, revoke, and check readiness
fjall ci token list
fjall ci token revoke <id> --reason "pipeline decommissioned"
fjall ci status

Store the token as FJALL_API_KEY in your CI provider’s secrets.

Workflow Setup

fjall ci setup --plan reports the CI provider, repository, and application it detects, plus the path of the workflow file it would write — it prints no file contents, mints nothing, and writes nothing. fjall ci verify dry-runs the auth handshake — credential, principal kind, expiry runway, and application access — before your first pipeline run:

fjall ci setup --app api --plan   # report detected provider/app + target path (mints and writes nothing)
fjall ci verify --app api         # exit 0 = ready, exit 1 = at least one check failed

fjall ci setup without --plan attempts to mint the deploy token before it writes anything, and the API only permits minting from an interactive browser session — so the command fails with guidance and writes no workflow file. Mint the token in the web app (Settings → CI/CD Tokens) and copy the workflow YAML from the examples on this page.

GitHub Actions

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

Minimal Workflow (Recommended)

A CI deploy token is the only secret you need. The CLI exchanges it for short-lived AWS credentials scoped to the deploy, and the run is recorded in your Fjall dashboard:

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

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

      - uses: fjall-tech/fjall-deploy-action@v3
        with:
          target: api
        env:
          FJALL_API_KEY: ${{ secrets.FJALL_API_KEY }}

Mint the token in the web app (Settings → CI/CD Tokens) and store it as the FJALL_API_KEY repository secret. Your AWS account must already be connected to Fjall.

With AWS OIDC

If you prefer AWS-native credential management, use GitHub’s OIDC provider to assume an IAM role — 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-tech/fjall-deploy-action@v3
        with:
          target: api
          verbose: true
        env:
          FJALL_API_KEY: ${{ secrets.FJALL_API_KEY }}

With Static AWS Credentials

Store AWS keys as repository secrets. Simplest to set up, but the keys are long-lived and need rotation:

steps:
  - uses: actions/checkout@v4

  - uses: fjall-tech/fjall-deploy-action@v3
    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
      FJALL_API_KEY: ${{ secrets.FJALL_API_KEY }}

A deploy authenticated with AWS credentials alone still works, but Fjall cannot see it: the run is missing from your deployment history, and it creates no release record to roll back to. Keep FJALL_API_KEY set on every deploy step, whichever AWS credential method you use.

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-tech/fjall-deploy-action@v3
        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-tech/fjall-deploy-action@v3
        with:
          target: api
          mode: deploy-only

Action Inputs

The action is a thin shim onto fjall ci run: every input maps 1:1 to a CLI flag, and the CLI owns command and flag validation.

Input	Required	Default	Description
`command`	no	`deploy`	`deploy`, `destroy`, or `build`
`target`	yes	—	App name, `organisation`, `platform`, or `account`
`service`	no	—	Specific service name (deploy and build only)
`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 (use with `mode: deploy-only` when the image is already pushed)
`skip-migrations`	no	`false`	Skip database migrations during this deployment
`no-cascade`	no	`false`	Skip cascade around organisation deploys and destroys
`region`	no	—	Deploy to a specific region within the target’s account
`image-tag`	no	—	Roll forward or back to an existing image tag (skips build, implies deploy-only)
`plan`	no	`false`	Compute and print the change plan, then stop before any mutation
`require-approval`	no	`false`	Refuse to mutate unless the plan is approved via `auto-approve` or `approval-token`
`auto-approve`	no	`false`	Approve the computed plan without prompting (use with `require-approval`)
`approval-token`	no	—	Resume an approved plan from a prior `plan` run; the plan digest is re-verified
`build-args`	no	—	Public build-time args, newline-separated `KEY=VALUE` pairs
`build-secrets`	no	—	Build secret refs, newline-separated `id=ID,ssm=PATH` (or `secretsManager=NAME` \| `env=VAR`)
`cli-version`	no	`7`	`fjall` version to install: an exact version, a major, `auto`, or `latest`
`working-directory`	no	`.`	Directory containing `fjall-config.json`
`force`	no	`false`	Deploy: redeploy unchanged stacks. Destroy: skip destruction confirmation

Action Outputs

Output	Description
`result`	`success`, `plan-pending` (changes pending approval or rejected at the gate), or `failure`
`duration`	Command duration in seconds
`approval-token`	Token emitted by a `plan` run with pending changes; feed it back via the `approval-token` input

A plan run with pending changes exits 2 (surfaced as result: plan-pending), so a plan→approve→apply pipeline can branch on it without treating it as a failure.

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.

cli-version defaults to 7 — the CLI major this plugin release is built for, and the same major as current @fjall/components-infrastructure releases. Set it to auto to derive the major from your app’s constructs pin instead, or to an exact version you’ve validated locally (fjall --version). Avoid latest: it floats across releases, and if it drifts behind your app’s constructs the deploy is refused by the engine compatibility check.

Buildkite

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

Minimal Pipeline

steps:
  - label: ":rocket: Deploy"
    env:
      FJALL_API_KEY: "${FJALL_API_KEY}"
    plugins:
      - fjall-tech/fjall-deploy#v3:
          target: api

Expose FJALL_API_KEY through your Buildkite secrets storage (for example the S3 secrets plugin or your agent environment hooks). The same tracking caveat applies as on GitHub Actions: without it, deploys run but are invisible to Fjall. The cli-version guidance above applies here too.

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-tech/fjall-deploy#v3:
          target: api

Staging to Production Pipeline

steps:
  - label: ":test_tube: Staging"
    plugins:
      - fjall-tech/fjall-deploy#v3:
          target: api
          environment: staging

  - wait

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

  - label: ":rocket: Production"
    plugins:
      - fjall-tech/fjall-deploy#v3:
          target: api
          environment: production
          skip-build: true

Plugin Properties

The plugin is a thin shim onto fjall ci run and accepts the same surface as the GitHub action. build-args and build-secrets are YAML arrays of strings rather than newline-separated blocks:

Property	Required	Default	Description
`command`	no	`deploy`	`deploy`, `destroy`, or `build`
`target`	yes	—	App name, `organisation`, `platform`, or `account`
`service`	no	—	Specific service name (deploy and build only)
`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
`skip-migrations`	no	`false`	Skip database migrations during this deployment
`no-cascade`	no	`false`	Skip cascade around organisation deploys and destroys
`region`	no	—	Deploy to a specific region within the target’s account
`image-tag`	no	—	Roll forward or back to an existing image tag (skips build, implies deploy-only)
`plan`	no	`false`	Compute and print the change plan, then stop before any mutation
`require-approval`	no	`false`	Refuse to mutate unless the plan is approved via `auto-approve` or `approval-token`
`auto-approve`	no	`false`	Approve the computed plan without prompting (use with `require-approval`)
`approval-token`	no	—	Resume an approved plan from a prior `plan` run
`build-args`	no	—	Array of `KEY=VALUE` public build-time args
`build-secrets`	no	—	Array of `id=ID,ssm=PATH` (or `secretsManager=NAME` \| `env=VAR`) secret refs
`cli-version`	no	`7`	`fjall` version to install: an exact version, a major, `auto`, or `latest`
`working-directory`	no	`.`	Directory containing `fjall-config.json`
`force`	no	`false`	Deploy: redeploy unchanged stacks. Destroy: skip destruction confirmation

The plugin records fjall-deploy:result, fjall-deploy:duration, and any fjall-deploy:approval-token as build meta-data (buildkite-agent meta-data get fjall-deploy:result), and a plan-pending run adds a warning annotation to the build.

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 — match the major of your app's
# @fjall/components-infrastructure pin (see Engine Compatibility)
npm install -g fjall@7

# Authenticate with a CI deploy token
export FJALL_API_KEY="fjall_dk_..."

# Deploy
fjall ci run deploy api

fjall ci run <deploy|destroy|build> <target> is the single CI entry point — the same command both official plugins invoke under the hood. It forces non-interactive output and skips confirmation prompts, and rejects flags that don’t apply to the command you’re running (for example, deploy-only flags on a destroy).

Key Flags

Flag	Description
`--mode <mode>`	Deploy mode: `full`, `infra-only`, or `deploy-only` (default: `full`)
`--service <name>`	Deploy a single service
`--environment <env>`	Free-form CI/CD label passed to CDK synthesis (not an account selector)
`--skip-build`	Skip Docker build (use with `--mode deploy-only`)
`--skip-migrations`	Skip database migrations during this deployment
`--region <region>`	Deploy to a specific region within the target’s account
`--image-tag <tag>`	Deploy an already-pushed image tag (skips build, implies deploy-only)
`--plan`	Plan only — stop at the approval gate
`--require-approval`	Require an approval token to proceed
`--auto-approve`	Approve the plan gate without prompting
`--approval-token <token>`	Approval token from a prior `--plan` run
`--remediate <name=verb>`	Named consent for a pending destructive change (repeatable; exact, case-sensitive physical name; deploy only)
`--allow-replace <name>`	Shorthand consent: equivalent to `--remediate <name>=recreate` (repeatable; deploy only)
`--destruction-consent-digest <digest>`	Bind consents to the ticket digest from a prior `--plan` run (deploy only)
`--build-arg <KEY=VALUE>`	Public build-time arg (repeatable)
`--build-secret <ref>`	Ad-hoc build secret ref (repeatable): `id=ID` with `ssm=PATH` \| `secretsManager=NAME` \| `env=VAR`
`--no-cascade`	Skip cascade for organisation deploys
`-v, --verbose`	Enable verbose logging
`--force`	Redeploy all stacks even when no changes are detected

Invoking fjall deploy api --non-interactive --skip-confirmation directly still works; fjall ci run wraps the same engine with CI-safe defaults.

Exit Codes

Code	Meaning
`0`	Success, or a plan run with no changes
`2`	Plan pending approval, or rejected at the approval gate
`4`	The destruction gate stopped the deploy: consent withheld, declined, invalid, not yet executable, or a consented `pin` was applied and the deploy stopped for the config write-back. Nothing was applied to AWS
`1`	Failure
`64`	A prerequisite is missing (Docker buildx)
`130`	Interrupted (SIGINT)

Exit 4 means the deploy stopped at the destruction gate. It is a decision, not a failure, and the cure depends on the outcome printed with the ticket. When consent was withheld, surface the printed ticket to a human and re-run with the named consents once reviewed (ideally minted from a --plan run and bound with --destruction-consent-digest). A consented pin has already written the config change: commit it and re-run without re-supplying the consent. A declined, invalid, or not-yet-executable consent prints what to change. Always follow the printed cure.

Never auto-inject --remediate or --allow-replace in a pipeline. A consent baked into CI silently approves the next unrelated change that replaces a resource of the same name. See Exit code 4 in CI.

Environment Variables

Variable	Description
`FJALL_API_KEY`	CI deploy token (`fjall_dk_...`) — authenticates to Fjall and mints AWS credentials
`AWS_ACCESS_KEY_ID`	AWS access key (only if not using a deploy token for AWS access)
`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:24
  variables:
    FJALL_API_KEY: $FJALL_API_KEY
  script:
    - npm install -g fjall@7
    - fjall ci run deploy api --verbose
  only:
    - main

Example: CircleCI

jobs:
  deploy:
    docker:
      - image: cimg/node:24.0
    steps:
      - checkout
      - run: npm install -g fjall@7
      - run: fjall ci run deploy api --verbose

Set FJALL_API_KEY as a project secret in either system.

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:

Fjall Deploy Token (Recommended)

Set FJALL_API_KEY to a CI deploy token and skip AWS credential setup entirely. The CLI exchanges the token for short-lived, deploy-scoped AWS credentials in your connected account, and every run is tracked in your dashboard.

AWS OIDC Federation

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.

Install & Setup

Application Deploy

Deployment Errors

Organisation Setup

Organisation Deploy

CI/CD Integration

Introduction

CI Deploy Tokens

Minting and Managing Tokens

Workflow Setup

GitHub Actions

Minimal Workflow (Recommended)

With AWS OIDC

With Static AWS Credentials

Split Infrastructure and Code Deploys

Action Inputs

Action Outputs

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

Fjall Deploy Token (Recommended)

AWS OIDC Federation

Static Credentials

Instance Profiles

Next Steps

Deploy an Application

deploy Command Reference

Understanding Profiles

Configure a Deployment User

​Introduction

​CI Deploy Tokens

​Minting and Managing Tokens

​Workflow Setup

​GitHub Actions

​Minimal Workflow (Recommended)

​With AWS OIDC

​With Static AWS Credentials

​Split Infrastructure and Code Deploys

​Action Inputs

​Action Outputs

​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

​Fjall Deploy Token (Recommended)

​AWS OIDC Federation

​Static Credentials

​Instance Profiles

​Next Steps

Deploy an Application

deploy Command Reference

Understanding Profiles

Configure a Deployment User

Introduction

CI Deploy Tokens

Minting and Managing Tokens

Workflow Setup

GitHub Actions

Minimal Workflow (Recommended)

With AWS OIDC

With Static AWS Credentials

Split Infrastructure and Code Deploys

Action Inputs

Action Outputs

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

Fjall Deploy Token (Recommended)

AWS OIDC Federation

Static Credentials

Instance Profiles

Next Steps