CI/CD deployments

This guide walks through deploying a Flyte project from CI. It uses GitHub Actions as the reference implementation, but the building blocks — an API key secret, flyte deploy, and a commit-pinned version — translate to GitLab CI, Buildkite, CircleCI, or any runner that can run a Python script.

The examples below assume the project layout and image definitions from the Monorepo with uv pattern — that guide covers how to structure pyproject.toml, envs.py, and task modules in a way that makes the flyte deploy commands shown here work cleanly.

What CI needs to do

A deploy pipeline has three jobs:

1. Install the project and the flyte CLI.
2. Authenticate non-interactively against your tenant.
3. Run flyte deploy for every TaskEnvironment in your project, pinned to the commit SHA.

Everything else — branch protections, approvals, notifications — is generic CI concerns and out of scope.

Authentication: API keys

Locally, flyte deploy typically authenticates via a browser login (PKCE). A CI runner has no browser and no human to click through a consent screen, so you need a credential the CLI can use without any prompts — an API key.

Mint the key

The flyte create api-key command is provided by the flyteplugins-union package. Add it to a dev dependency group so it’s available locally but not baked into task images:

# pyproject.toml
[dependency-groups]
dev = ["flyteplugins-union"]

Then, from a machine already logged in to your tenant:

uv run flyte create api-key --name ci-cd-key

The output is a single base64-encoded string of the form endpoint:client_id:client_secret:org. It’s shown only once — copy it immediately.

The creation call doesn’t take a permissions argument — the key is created under the caller’s organization and identity context. If you need the key’s privileges to be narrower than the minting user’s, assign a dedicated role or policy to the key’s identity using flyte create role, flyte create policy, and flyte create assignment.

Store the key as a CI secret

Add the string to your CI system’s secret store. However it’s configured, the secret needs to:

• Be exposed to the deploy job as an environment variable named FLYTE_API_KEY.
• Be masked in logs (most CI systems do this automatically for secrets).
• Be scoped to the branches/environments that actually deploy — typically main or a release branch, not every feature branch or fork PR.

When FLYTE_API_KEY is present in the environment at deploy time, the flyte CLI uses it for ClientSecret auth, overriding any auth mode configured in config.yaml.

Key scope and rotation

The key inherits the permissions of the user who minted it. For CI you typically want a dedicated service identity with narrow scope — deploy rights on the target project/domain only. Rotate on a schedule (90 days is a reasonable default) by running flyte create api-key again and updating the secret.

Project configuration

Two files drive flyte deploy behavior in CI: pyproject.toml (or uv.lock) for dependencies, and config.yaml for tenant endpoints.

config.yaml

Check this into the repo. It supplies the project, domain, and image builder settings — the things the API key doesn’t carry:

admin:
  endpoint: dns:///<tenant>.hosted.unionai.cloud
image:
  builder: remote
task:
  project: <default-project>
  domain: development

The GitHub Actions workflow

A minimal deploy workflow — one job, one step per TaskEnvironment:

# .github/workflows/deploy.yml
name: Deploy to Union

on:
  push:
    branches: [main]
  workflow_dispatch:

env:
  FLYTE_PROJECT: my-project
  FLYTE_DOMAIN: development

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

      - name: Install uv
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true

      - name: Sync dependencies
        run: uv sync --group etl --group ml --group dev

      - name: Deploy etl_env
        env:
          FLYTE_API_KEY: ${{ secrets.FLYTE_API_KEY }}
        run: |
          uv run flyte deploy \
            --copy-style none \
            --version ${{ github.sha }} \
            --project "$FLYTE_PROJECT" \
            --domain "$FLYTE_DOMAIN" \
            src/workspace_app/tasks/etl_tasks.py etl_env

      - name: Deploy ml_env
        env:
          FLYTE_API_KEY: ${{ secrets.FLYTE_API_KEY }}
        run: |
          uv run flyte deploy \
            --copy-style none \
            --version ${{ github.sha }} \
            --project "$FLYTE_PROJECT" \
            --domain "$FLYTE_DOMAIN" \
            src/workspace_app/tasks/ml_tasks.py ml_env

Key flag choices

• --copy-style none — bakes source into the image as part of the build layer. Combined with .with_code_bundle() on your flyte.Image (see Monorepo with uv), this resolves to a COPY instruction so the image is fully self-contained. This is the production path: one immutable artifact per commit, no runtime code bundle download.

• --version ${{ github.sha }} — makes deploys idempotent and traceable. Re-running the same commit produces the same version identifier; tasks already registered at that version are no-ops.

• Path argument points at the task file, not envs.py. flyte deploy only imports the file you give it, so tasks decorated with @env.task in separate files won’t register unless you point at (or transitively import) those files. Pointing at etl_tasks.py pulls in envs.py via its import chain and runs the @etl_env.task decorators. As an alternative, you can point at a directory and pass --recursive to load every task module under it in one command — for a src/ layout project, also pass --root-dir src so shared modules like envs.py resolve to a single import path instead of being loaded twice:

  - name: Deploy all envs
    env:
      FLYTE_API_KEY: ${{ secrets.FLYTE_API_KEY }}
    run: |
      uv run flyte deploy \
        --copy-style none \
        --version ${{ github.sha }} \
        --project "$FLYTE_PROJECT" \
        --domain "$FLYTE_DOMAIN" \
        --root-dir src --recursive src/workspace_app/tasks

Splitting build from deploy

flyte deploy builds any missing images before it registers tasks. If you’d rather treat image builds as a separate CI concern — for clearer logs, independent retry, or parallel builds per env — run flyte build first and let deploy reuse the result:

- name: Build etl image
  env:
    FLYTE_API_KEY: ${{ secrets.FLYTE_API_KEY }}
  run: |
    uv run flyte build \
      --copy-style none --root-dir src \
      src/workspace_app/tasks/etl_tasks.py etl_env

- name: Deploy etl_env
  env:
    FLYTE_API_KEY: ${{ secrets.FLYTE_API_KEY }}
  run: |
    uv run flyte deploy \
      --copy-style none \
      --version ${{ github.sha }} \
      --project "$FLYTE_PROJECT" --domain "$FLYTE_DOMAIN" \
      --root-dir src src/workspace_app/tasks/etl_tasks.py etl_env

Image tags are content hashes of the flyte.Image definition: flyte build pushes <registry>:flyte-<hash>, and flyte deploy computes the same hash, sees the image already in the registry, and skips rebuilding. --copy-style must match between the two commands — otherwise the hashes diverge and deploy will build again.

Layering on top of an existing image build

If your team already builds container images in CI from a Dockerfile, you can still route them through flyte build to get lazy-loading container pulls — pod startup that’s seconds instead of minutes, regardless of image size. On a 5GB image we measured cold-node pull time drop from ~1m37s to 839ms, and published benchmarks show 9.9GB CUDA + PyTorch images going from 4m38s to ~1.2s — roughly 240×.

You get this for free whenever you use flyte.Image with the remote builder. Images built outside of it — straight from your own docker build and docker push — don’t get the optimization, which is why this section adds a single flyte build step on top of your existing pipeline.

How it works: rather than downloading the full image up front, the cluster fetches a small (~14MB) metadata index, mounts the filesystem immediately, and streams file chunks from the registry as the container actually reads them. Files the task never touches never transfer, and chunks are cached on the node so subsequent pulls of the same or related images are sub-second.

The CI shape is two stages: your existing job builds and pushes the base, then a follow-up job runs flyte build to layer on top and flyte deploy to register tasks against the result.

# .github/workflows/deploy.yml
jobs:
  build-base:
    runs-on: ubuntu-latest
    outputs:
      base_uri: ${{ steps.build.outputs.uri }}
    steps:
      # Whatever your team already does to build and push the base image.
      # Output the full URI tagged with the commit SHA.
      - id: build
        run: |
          ./your-existing-build.sh
          echo "uri=ghcr.io/myorg/base:${{ github.sha }}" >> "$GITHUB_OUTPUT"

  deploy:
    needs: build-base
    runs-on: ubuntu-latest
    env:
      BASE_IMAGE: ${{ needs.build-base.outputs.base_uri }}
      FLYTE_API_KEY: ${{ secrets.FLYTE_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv sync --group dev
      - run: uv run flyte build --copy-style none --root-dir src src/myproj/envs.py train_env
      - run: uv run flyte deploy --copy-style none --version ${{ github.sha }} --root-dir src src/myproj/envs.py train_env

envs.py reads the base URI from the environment, so each commit’s overlay is pinned to that commit’s base:

# src/myproj/envs.py
import os
import flyte

train_env = flyte.TaskEnvironment(
    name="train",
    image=flyte.Image.from_base(os.environ["BASE_IMAGE"]).clone(
        name="train", extendable=True,
    ),
)

The flyte build job is idempotent — it skips when the same image content has already been published. Workflow code edits don’t trigger image rebuilds; only envs.py or base-image changes do.