FAQ

This section covers common questions, edge cases, and troubleshooting for JFrog Fly.

Overview

Onboarding & Setup - Account creation, subdomains, and GitHub connection
Fly App - Local setup, coding agents, and platform support
Package Management - Uploading, downloading, and public registry behavior
CI & Releases - Workflow configuration and release creation
Runtime & Deployment - Environments, tracking, and Kubernetes
Troubleshooting - Symptom-based fixes for common issues

Quick Links

Onboarding & Setup

Fly App

Package Management

CI & Releases

Runtime & Deployment

Troubleshooting

Onboarding & Setup

What is a “team subdomain” and why does it matter?

Your team subdomain is the unique identifier for your team’s Fly Registry, created when you pick your team name during account creation.

Format: <your-team-subdomain>.jfrog.io

Your subdomain is used in every registry URL across Fly:

Package managers: <your-fly-subdomain>.jfrog.io/artifactory/api/npm/npm/
Docker images: <your-fly-subdomain>.jfrog.io/docker/my-image:latest
Maven/Gradle: <your-fly-subdomain>.jfrog.io/artifactory/maven
CI/CD workflows: All Fly action configurations

Example: If your team subdomain is acmecorp, all your developers will use URLs like:

acmecorp.jfrog.io/docker/api:v1.2.3
acmecorp.jfrog.io/artifactory/api/npm/npm/

Can I change my team subdomain later?

No. Your subdomain is permanent and cannot be changed. All registry URLs, workflows, and configurations depend on it, so choose carefully.

Do I need to be an admin of my GitHub organization to connect it?

Yes. You must be an owner or admin of the GitHub organization to install the JFrog Fly GitHub App. If you’re not an admin, ask one to connect it. For personal repositories, you only need to own the repository.

How do I enable two-factor authentication?

Go to Account Settings > Password & Authentication in Fly Web. In the Two-factor authentication methods section, click Add on the Authenticator App card and scan the QR code with your authenticator app. See Team Management → for details.

Fly App

What is “Fly MCP” and do I need it?

Fly MCP (Model Context Protocol) connects your coding agent directly to Fly, so you can take any action with natural language.

With Fly MCP enabled, your coding agent can do everything:

“Configure my repo to work with Fly”
“Push this image”
“Deploy the release with the authentication fix to production”
“Is production up to date?”
“Find the release where I fixed the login bug”
“Create a staging environment”

Requirements: Fly App installed and the coding agent connection toggled on in the app. Once it’s on, you’re connected.

What Coding Agents are supported?

Currently supported: Cursor, Copilot, Claude Code, and OpenCode.

The Fly App automatically detects and integrates Fly MCP with supported Coding Agents.

Is Fly available on Windows or Linux?

Fly App supports macOS and Windows. Fly Web, CI/CD integration, and Registry work on all platforms.

Package Management

What public registries does Fly proxy?

Technology	Public Registry
npm	https://registry.npmjs.org
pip	https://files.pythonhosted.org (PyPI)
Maven	https://repo1.maven.org/maven2 (Maven Central)
Docker	https://registry-1.docker.io (DockerHub)
Helm	https://registry-1.docker.io (DockerHub)
Go	https://proxy.golang.org
NuGet	https://www.nuget.org
Gradle	https://repo1.maven.org/maven2 (Maven Central)

What happens to public dependencies I download?

Fly checks your uploaded artifacts first, then fetches from the public registry and caches it for your team. Cached packages download faster and are available even if the public registry is down.

Can I upload files that aren’t packages?

Yes. Ask your coding agent to upload any file to Fly. Release binaries, build outputs, signed archives, or anything your team needs to version and share. Fly stores and organizes them as generic packages. See Generic → for details.

CI & Releases

Can I edit a release title or description?

Yes. Open any release’s detail page in Fly Web and click on the Title or Description to edit. Changes are saved immediately and reflected in semantic search.

Can I search for releases using natural language?

Yes. You can search for releases from any interface: your coding agent, Fly Web, or even Slack. Simply ask semantically:

“Find the release where I fixed the login bug”
“Show me Jon’s last deployment”
“Releases from last week with API changes”

How do I skip specific package managers in CI?

By default, the Fly action configures all supported package managers. To skip specific ones, use the ignore input:

- uses: jfrog/fly-action@v1
  with:
    ignore: docker,pip

See Automate Releases → for more CI configuration options.

Runtime & Deployment

Do I need to create an environment from Fly Web?

No. Ask your coding agent: “Create a staging environment” and Fly handles it. You can also create environments from Fly Web if you prefer.

How can I see my deployments in Fly?

Connect your environment with an environment-scoped token applied as a Kubernetes image pull secret. Once connected, every image pull is tracked automatically and appears in the environment dashboard in Fly Web. No extra configuration needed.

What happens when I delete an environment?

Deleting an environment revokes all associated tokens and removes historical data. This action cannot be undone and requires explicit confirmation.

Troubleshooting

Why isn’t my workflow creating releases?

A release is created only when all of these conditions are met:

Workflow has the Fly action configured
Workflow has the required OIDC permissions block
Workflow completes successfully
At least one artifact is uploaded to Fly Registry

Check these:

Verify the Fly action is present in your workflow:

- uses: jfrog/fly-action@v1            # Setup Fly package managers

Verify the permissions block is at the top level:

permissions:
  contents: read
  id-token: write

Check workflow logs for Fly action output
Confirm artifact upload succeeded in package manager logs (npm publish, docker push, etc.)

Why does Next.js fail to download SWC packages in CI?

Symptom: next build fails with a 401 error downloading SWC binaries like @next/swc-linux-x64-gnu, even though the Fly action is configured.

Failed to download swc package from https://<subdomain>.jfrog.io/artifactory/api/npm/npm/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-16.1.5.tgz
unhandledRejection Error: request failed with status 401

Cause: This is a known Next.js bug. When Next.js detects missing SWC binaries in your lockfile, it tries to download them using its own internal HTTP client, which does not send the npm auth token from .npmrc. The request hits the registry without authentication. This happens with any authenticated registry, not just Fly.

Fix: Regenerate your lockfile locally so SWC binaries are resolved as proper dependencies:

rm -rf node_modules package-lock.json
npm install

Commit the updated package-lock.json and push. When npm ci runs in CI, it installs the SWC binaries through npm (with auth), and next build finds them already present.

Why do I get a 401 error when pulling packages in CI?

Symptom: Package install or pull fails with a 401 (Unauthorized) error in your GitHub Actions workflow, even though the Fly action is configured.

Common causes:

Missing OIDC permissions. The permissions block must be at the top level of your workflow file, not inside a job:
```
permissions:
  contents: read
  id-token: write
```
Fly action placed after package commands. The Fly action must run before any package manager commands (npm install, docker pull, etc.).
Tool-specific auth bypass. Some tools (like Next.js SWC downloads) use their own HTTP clients that don’t read npm/pip/Docker auth config. See Why does Next.js fail to download SWC packages in CI?

Still Have Questions?

If you can’t find the answer you’re looking for:

Use Fly Chat → - Ask your question in natural language in the Fly Web
Browse Documentation → - Explore the detailed sections of this guide
Contact Support → - Reach out to JFrog support for assistance