fjall build

Overview

fjall build builds Docker images and pushes them to Amazon ECR. Use it in CI/CD pipelines that separate the build step from the deploy step, so you can test the exact image you are about to ship. The command is non-interactive by design. It prints a three-step progress stream and, with --output-image-url, a machine-readable block your pipeline can parse.

Prerequisites

Requirement	Why
Signed in to Fjall	Run `fjall login`. Fjall gets the AWS credentials as AWS Profiles and Targets describes, so no `aws` profile is required
Project bound to an org	`fjall build` refuses if the project’s `organisation` binding does not match your login
Network stack deployed	Run `fjall deploy <app>` at least once. The ECR repository lives in the Network stack
Docker running	The Docker daemon must be running on the build host

Usage

fjall build <app> [service] [options]

Arguments

Argument	Description	Required
`app`	Application name	Yes
`service`	Build only this service instead of every service	No

Options

Option	Description	Example
`--target <target>`	Docker build target stage for multi-stage Dockerfiles	`--target production`
`--output-image-url`	Print the pushed image URLs in a machine-readable block	`--output-image-url`
`--build-arg <KEY=VALUE>`	Public build-time arg, repeatable, highest precedence	`--build-arg NEXT_PUBLIC_API_URL=https://…`
`--build-secret <id=ID,ssm=PATH>`	Build secret reference, repeatable, never baked into layers	`--build-secret id=npm,ssm=/api/npm-token`
`-v, --verbose`	Show detailed output	`-v`
`--non-interactive`	Force plain CLI output	`--non-interactive`

--target on fjall build is the Docker build target stage. --target on fjall deploy is the deployment target (account and region). Same flag name, two different meanings.

Agent flags

These flags shape output for AI-agent and scripted callers.

Flag	Description
`--agent`	Enable agent output mode
`--budget <level>`	Output budget: `minimal`, `compact`, or a token count
`--fields <fields>`	Select exactly these output fields
`--full`	Disable content truncation

Basic usage

Build every service in an application:

fjall build api

Build one service:

fjall build api web

Build a named Dockerfile stage:

fjall build api --target production

Build arguments

--build-arg bakes a public value into the image at build time. It is repeatable, and it is the highest tier of the resolution ladder:

--build-arg  >  shell env var of the same name  >  .env.production  >  .env  >  the value declared in infrastructure.ts

fjall build dashboard \
  --build-arg NEXT_PUBLIC_API_URL=https://api.example.com \
  --build-arg NEXT_PUBLIC_ENV=production

Two rules govern which keys reach the build:

A key is emitted when your infrastructure.ts declares it, when you pass it via --build-arg, or when a key prefixed VITE_, NEXT_PUBLIC_ or PUBLIC_ is found in a parsed .env file.
Shell environment variables override the value of an already-declared key. They never introduce a new key, so arbitrary host environment cannot leak into the image.

An empty string at any tier counts as absent and falls through to the next tier.

A build arg is baked into the image layer and readable by anyone who can pull it. Use --build-secret for anything private.

Build secrets

--build-secret passes a value to the build through BuildKit’s secret mount, so it never lands in an image layer. It is repeatable, and each token is a comma-separated list of key=value pairs: an id plus exactly one source.

Key	Meaning
`id`	The BuildKit secret id your Dockerfile mounts
`ssm`	SSM Parameter Store path
`secretsManager`	Secrets Manager secret name
`field`	Optional JSON field inside a Secrets Manager secret
`env`	Environment variable on the build host

fjall build api \
  --build-secret id=npm,ssm=/api/production/NPM_TOKEN \
  --build-secret id=sentry,secretsManager=api-sentry,field=token

Mount it in your Dockerfile:

RUN --mount=type=secret,id=npm \
    NPM_TOKEN="$(cat /run/secrets/npm)" npm ci

Give each reference exactly one source: ssm, secretsManager or env. A malformed token fails the whole command before any AWS work starts, so a typo never reaches a build silently.

CI/CD workflow

The build command suits pipelines that:

Build and push the image.
Run tests against the pushed image.
Deploy that exact image without rebuilding.

fjall ci run build <target> [service] wraps this command with a resolved deployment target and CI deploy-token credentials. See fjall ci and the CI/CD integration guide.

Example: GitHub Actions

This is a workflow excerpt, not a complete pipeline. Each job runs on a fresh runner: install the CLI, check out the project where needed, supply a scoped CI deploy token, and authenticate Docker to ECR before pulling the private test image. Select the deployment target explicitly in the real pipeline. The extraction below is suitable only when the intended services share one build group; reject empty or multiple image selections before deploying.

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      image_url: ${{ steps.build.outputs.image_url }}
      image_tag: ${{ steps.build.outputs.image_tag }}
    steps:
      - uses: actions/checkout@v4

      - name: Build and push
        id: build
        run: |
          fjall build api --output-image-url --non-interactive | tee build.log
          IMAGE_URL=$(sed -n 's/^IMAGE_URL=//p' build.log)
          echo "image_url=$IMAGE_URL" >> "$GITHUB_OUTPUT"
          echo "image_tag=${IMAGE_URL##*:}" >> "$GITHUB_OUTPUT"

  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Run tests
        env:
          IMAGE_URL: ${{ needs.build.outputs.image_url }}
        run: docker run "$IMAGE_URL" npm test

  deploy:
    needs: [build, test]
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        env:
          IMAGE_TAG: ${{ needs.build.outputs.image_tag }}
        run: fjall deploy api --image-tag "$IMAGE_TAG" --non-interactive

--image-tag deploys the image the build step pushed, skipping the build and implying --deploy-only. It applies one tag family across the application’s services, so it fits applications whose services build from a single build group. For applications with independent build groups, deploy normally with fjall deploy api.

Example: Buildkite

This excerpt assumes an agent with the CLI, project checkout, deploy credentials and ECR Docker authentication already configured. Apply the same image-selection and explicit-target checks as above.

steps:
  - label: "Build"
    key: "build"
    command: |
      fjall build api --output-image-url --non-interactive | tee build.log
      buildkite-agent meta-data set image_url "$(sed -n 's/^IMAGE_URL=//p' build.log)"

  - label: "Test"
    depends_on: "build"
    command: |
      docker run "$(buildkite-agent meta-data get image_url)" npm test

  - label: "Deploy"
    depends_on: "test"
    command: |
      IMAGE_URL="$(buildkite-agent meta-data get image_url)"
      fjall deploy api --image-tag "${IMAGE_URL##*:}" --non-interactive

Output

Standard output

Building Docker image(s) for: api
  Target service: web

==> [1/3] Authenticating with AWS
<== [1/3] Authenticating with AWS (1.4s)

==> [2/3] Getting ECR repository
<== [2/3] Getting ECR repository (0.9s)

==> [3/3] Building and pushing Docker images
<== [3/3] Building and pushing Docker images (1m 12s)

── Summary ────────────────────────────────────────
  Result:   ✓ api built successfully
  Duration: 1m 15s
  Images:   web → web-sha-a1b2c3d4e5f6

Next steps:
  Run tests: docker run 123456789012.dkr.ecr.eu-west-1.amazonaws.com/api:web-sha-a1b2c3d4e5f6 npm test
  Deploy this build: fjall deploy api --image-tag web-sha-a1b2c3d4e5f6

The Deploy this build line appears only when every built artefact shares one digest. When services build from separate build groups, the last line reads Deploy: fjall deploy api instead. Image tags follow <service>-sha-<12 hex characters>, with a -<target> segment folded in for a multi-stage service. The tag identifies the service and the content of the build, not the git ref, so there is no --tag flag to override it.

Machine-readable output

Pass --output-image-url to print a parseable block:

============================================================
IMAGE_URL=123456789012.dkr.ecr.eu-west-1.amazonaws.com/api:web-sha-a1b2c3d4e5f6
IMAGE service=web tag=web-sha-a1b2c3d4e5f6 digest=sha256:0f3a… uri=123456789012.dkr.ecr.eu-west-1.amazonaws.com/api:web-sha-a1b2c3d4e5f6
============================================================

Line	Contents
`IMAGE_URL`	The first pushed image URL
`ALL_IMAGE_URLS`	Comma-separated list, printed only when more than one service was built
`IMAGE …`	One line per built artefact, with `service`, `tag`, `digest` and `uri`

Parse the per-service IMAGE lines when you need a specific service’s tag. IMAGE_URL is the first artefact, not a summary of the build.

Docker build targets

If your Dockerfile uses multi-stage builds with named targets:

FROM node:24 AS base
# ...

FROM base AS development
# ...

FROM base AS production
# ...

Build a specific stage:

fjall build api --target production

Troubleshooting

ECR repository not found

ECR repository not found in stack outputs (build). Looking for export: ApiEcrRepositoryName. Ensure Network stack has been deployed.

Cause: the application’s Network stack has never been deployed, so the ECR repository and its CloudFormation export do not exist. The export name is the PascalCase form of the application name plus EcrRepositoryName. Fix: deploy the infrastructure once.

fjall deploy api --infra-only

Docker build failed

Error: Docker build failed: ...

Cause: a Dockerfile error, a missing dependency, or an unmounted build secret. Fix: reproduce the build locally, then re-run.

docker build -t api-test .

AWS account ID unavailable

Error: AWS authentication succeeded but account ID is unavailable

Cause: before it builds anything, fjall build asks AWS STS which account its AWS credentials belong to (GetCallerIdentity), because it pushes to that account’s ECR registry. The call succeeded, but the answer named no account. AWS STS names the account whenever that call succeeds, so something else answered it. The AWS SDK inside the CLI sends STS calls to the endpoint that AWS_ENDPOINT_URL_STS or AWS_ENDPOINT_URL names, or that an endpoint_url in your AWS config file names, whenever one is set. Credentials that STS refuses stop the build with STS’s own error instead, so signing in again, to Fjall or to AWS, does not change this answer. Confirming a fjall login in this shell, or forcing one, would also replace the saved login for every shell and agent session that reads this state root. Fix: take the override away for the build. Unset the variable that sets it, or put AWS_IGNORE_CONFIGURED_ENDPOINT_URLS=true in front of the command: the SDK then ignores every configured endpoint, in the environment and the config file alike, for that one command.

# The AWS variables this shell sets, by name only
env | cut -d= -f1 | grep '^AWS_'

# Build with AWS's own endpoints
AWS_IGNORE_CONFIGURED_ENDPOINT_URLS=true fjall build api

When both AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are set, the CLI uses them in place of the credentials it derives for the target (see Environment credentials override derivation). If they are keys for the endpoint, such as a local AWS emulator’s, rather than for the account you deploy to, unset them as well: unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN. With no override set, something on the network path answered in AWS STS’s place, and the build needs a route to AWS STS itself.

Wrong organisation

Refusing to build: this project's fjall-config.json records organisation Acme (org_abc123)
as its home, but the credential in use belongs to Northwind (org_xyz789). Nothing was
created, synthesised or deployed. Cure: authenticate as Acme (org_abc123) ('fjall login',
or set FJALL_API_KEY to a key for that organisation), or — if this project really is
moving — run 'fjall org bind --org org_xyz789 --force' to re-bind it.

Cause: the organisation binding in fjall-config.json does not match the organisation your credential belongs to. The gate refuses only on a proven mismatch, and it runs before the first AWS call. Fix: authenticate as the bound organisation, or, if the project really is moving, rebind it by name. The fjall login the refusal names signs in again on the state root this shell already reads. That replaces the saved login for every shell and agent session that reads the root, whether you answer Yes at the overwrite prompt or pass --force. Where anything else is working on the machine, sign in to the bound organisation in a state root of its own instead:

# Sign in as the bound organisation in a state root of its own, then build from that root
FJALL_CONFIG_DIR=~/.fjall-acme fjall login --device --org org_abc123
FJALL_CONFIG_DIR=~/.fjall-acme fjall build api

# Or re-bind the project to the organisation the credential belongs to
fjall org bind --org org_xyz789 --force

On fjall login, --org takes the bound organisation’s id from the refusal, so the device flow signs you in to that organisation. The refusal’s other cure, FJALL_API_KEY set to a key for the bound organisation, also reaches it from one shell alone, because the CLI reads that variable before any stored credential. To keep the new root for later sessions, in a shell profile or a project’s agent settings, see Choosing an organisation.

Next steps

Deploy an application

Ship the image you just pushed

fjall deploy

Full reference for the deploy command, including --image-tag

fjall ci

Run builds and deploys from a CI pipeline

CI/CD integration

Pipeline templates, tokens, and exit codes

Documentation

Getting started

CLI reference

Patterns

Resources

Overview

Prerequisites

Usage

Arguments

Options

Agent flags

Basic usage

Build arguments

Build secrets

CI/CD workflow

Example: GitHub Actions

Example: Buildkite

Output

Standard output

Machine-readable output

Docker build targets

Troubleshooting

ECR repository not found

Docker build failed

AWS account ID unavailable

Wrong organisation

Next steps

Deploy an application

fjall deploy

fjall ci

CI/CD integration