FAQ

This section provides answers to common questions about JFrog Fly, organized by topic for easy navigation.

Overview

Find quick answers to frequently asked questions organized by topic:

Onboarding & Setup - Account creation and GitHub connection
JFrog Fly Desktop App - Local development setup
Package Management - Uploading and downloading artifacts
Automated Workflows - Configuring CI/CD workflows
Runtime Deployment - Deploying to runtime environments
Access & Team Management - Managing users and tokens

Quick Links

Onboarding & Setup

JFrog Fly Desktop App

Package Management

Automated Workflows

Runtime Deployment

Access & Team Management

Onboarding & Setup

How do I create a new account?

To join JFrog Fly, you must first join the beta waiting list program.

Navigate to the JFrog Fly website and request to join the waiting list
Once approved, you’ll receive an email invitation to sign up
Follow the link in the email to begin the two-step sign-up process:
- Create User: Choose your authentication method (GitHub, Google, or Email + Password)
- Team Setup: Define your team’s name (which creates your unique registry subdomain) and agree to the terms and conditions

The user who creates the account will automatically be designated as the Admin of the team.

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

Your team subdomain is the unique identifier for your team’s Fly Registry, created during the Team Setup step of account creation.

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

Why it matters:

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 team subdomain is permanent and cannot be changed after creation.

Why it’s permanent:

All artifacts are stored using this subdomain
All registry URLs contain this subdomain
CI/CD workflows reference this subdomain
Team members’ configurations use this subdomain

Best practice: Choose a subdomain that represents your organization or team name clearly and professionally (e.g., acmecorp, productteam, mycompanydev).

If you need a different subdomain: You would need to create a new Fly account with a different subdomain and migrate your artifacts and workflows.

How do I connect my GitHub organization?

After creating your account, the Fly Web App will guide you to connect your GitHub organization via the GitHub App integration.

During this process, you’ll be prompted to select repositories:

Select specific repositories: Gives you granular control
Select all repositories: Recommended approach to avoid reconnecting when creating new repositories

Once connected, Fly will begin tracking the artifacts, releases, and workflows in those repositories.

To manage your organizations and repositories later:

Navigate to Git Repositories in the Fly Web App
Click Manage Org & Repositories
You’ll be redirected to GitHub to manage the JFrog Fly GitHub App permissions

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.

Why admin access is required: GitHub requires admin/owner permissions to install apps to an organization.

If you’re not an admin: Ask an admin/owner to connect the organization. Once connected, any Fly team member can view repositories, releases, and workflows.

Note: For personal repositories, you only need to own the repository.

JFrog Fly Desktop App

How do I install the Fly Desktop App?

In the Fly Web App, click on the Desktop icon
Click Connect to download the Desktop App
Run the installer and follow the installation wizard
Launch the app and log in with your Fly credentials
The app automatically detects and suggests configuration for your package managers and Agentic IDEs

Currently supported: macOS only (Windows and Linux support coming soon)

How do I get my local environment configured?

The Fly Desktop App automates your local environment setup:

Install and log in to the Desktop App
App automatically detects your local package managers (npm, pip, docker, maven, etc.) and Agentic IDEs (Cursor, VS Code Copilot)
Click Configure to set up all detected tools, or configure specific ones later

Once configured, two things happen automatically:

Your package managers are connected to the Fly Registry
The Fly MCP tool is integrated with your IDE for AI-powered workflows

You can also select a default IDE which Fly will use for workflows like configuring CI/CD.

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

Fly MCP (Model Context Protocol) lets you use natural language commands in your IDE for package management and workflow configuration.

Examples:

“Configure my workflows with Fly”
“Publish this package to Fly”
“Find the release with the login fix”

Do you need it? No, but it makes working with Fly much easier. Automatically installed when you configure Cursor or VS Code Copilot through the Desktop App.

What Agentic IDEs are supported?

Currently supported:

Cursor
VS Code Copilot

Coming soon:

Claude CLI
Gemini CLI

The Desktop App automatically detects and integrates Fly MCP with supported IDEs.

Is Fly available on Windows or Linux?

Currently: Fly Desktop App supports macOS only.

Coming soon: Windows and Linux support.

Note: Fly Web, CI/CD integration, and Registry work on all platforms. Only the Desktop App is currently macOS-specific.

Package Management

How do I upload an artifact?

Option 1: Desktop App (Recommended)

Requirements: Make sure your Desktop App is installed and your package manager is configured.

Use your regular commands, or prompt your IDE with Fly MCP:

npm publish
twine upload dist/*
mvn deploy

Fly handles authentication automatically!

For Docker: Include your Fly subdomain in the image path (if using Fly MCP in your IDE, it adds the path automatically):

docker push <your-fly-subdomain>.jfrog.io/docker/my-app:tag

Option 2: Manual with Token

Generate an access token → in Fly Web App (Read & Write permission)
Configure your package manager with the token
Use standard commands

View package manager configuration guides →

Note: You can also upload artifacts automatically via CI/CD by configuring your GitHub Actions workflow to work with Fly. Learn more →

How do I upload and download a Docker image locally?

Option 1: Desktop App (Recommended)

Requirements: Make sure your Desktop App is installed and Docker is configured.

Use your regular Docker commands (include your Fly subdomain in the image path), or prompt your IDE with Fly MCP:

# Upload
docker push <your-fly-subdomain>.jfrog.io/docker/my-image:latest

# Download
docker pull <your-fly-subdomain>.jfrog.io/docker/my-image:latest

Fly handles authentication automatically!

Using Fly MCP in your IDE? Use natural language prompts - it adds the subdomain automatically:

“Push this Docker image to Fly”
“Pull my-app:latest from Fly”

Option 2: Manual with Token

Generate an access token → in Fly Web App (Read & Write permission)
Login to the Fly Docker registry:

docker login <your-fly-subdomain>.jfrog.io/docker -u <your-fly-username> -p <your-fly-token>

Use standard Docker commands:

# Upload
docker push <your-fly-subdomain>.jfrog.io/docker/my-image:latest

# Download
docker pull <your-fly-subdomain>.jfrog.io/docker/my-image:latest

How do I upload and download an npm package?

Option 1: Desktop App (Recommended)

Requirements: Make sure your Desktop App is installed and npm is configured.

Use your regular npm commands, or prompt your IDE with Fly MCP:

# Upload
npm publish

# Download
npm install <package-name>

Fly handles authentication automatically!

Using Fly MCP in your IDE? Use natural language prompts:

“Publish this npm package to Fly”
“Install my-private-package from Fly”

Option 2: Manual with Token

Generate an access token → in Fly Web App (Read & Write permission)
Add this to your .npmrc file:

registry=https://<your-fly-subdomain>.jfrog.io/artifactory/api/npm/npm/
//<your-fly-subdomain>.jfrog.io/artifactory/api/npm/npm/:_authToken=<your-fly-token>

Use standard npm commands:

npm publish
npm install <package-name>

How do I manually upload a Python package using a token?

Generate an access token in the Fly Web App (Read & Write permission)
Create or update ~/.pypirc file:

[distutils]
index-servers = fly

[fly]
repository = https://<your-fly-subdomain>.jfrog.io/artifactory/api/pypi/pypi
username = <your-fly-username>
password = <your-fly-token>

Build your package:

python setup.py sdist bdist_wheel

Upload with twine:

twine upload -r fly dist/*

What public registries does Fly proxy?

Fly acts as a proxy for these public registries, allowing you to access public dependencies:

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)
Go	https://proxy.golang.org
NuGet	https://www.nuget.org

When you request a public dependency, Fly checks your uploaded artifacts first, then fetches from the public registry and caches it for future use.

Automated Workflows

How do I configure my CI workflow to work with Fly?

Fly currently supports GitHub Actions only.

The Fly GitHub action configures your supported package managers in your workflow runner and handles authentication for you, so you can simply use your regular commands (npm publish, pip install, docker push, etc.).

You can configure your workflows in two ways:

Option 1: Agentic with MCP (Recommended)

Requirements: Make sure your Desktop App is installed and connected with Fly MCP (supported in Cursor and VS Code Copilot)

See guide on how to install and connect the Desktop App →

Steps:

Open your IDE
Prompt:

Configure my workflows with Fly

Review the changes - Fly MCP automatically adds these snippets to your .github/workflows/*.yml files:

1. Permissions (top level, after on:):

permissions:
  contents: read
  id-token: write

2. Fly Action (after package manager setup steps like actions/setup-node, before artifact operations like npm install, docker push):

- name: JFrog Fly - Configure all your package managers to work with Fly registry
  uses: jfrog/fly-action@v1
  with:
    url: https://<your-fly-subdomain>.jfrog.io

Commit and push

For Docker: Include your Fly subdomain in image names: <your-fly-subdomain>.jfrog.io/docker/my-app:tag

Option 2: Manual

Add the same snippets from Option 1 manually to your .github/workflows/*.yml files.

Make sure:

The permissions block is at the top level of your workflow file (after on:, before jobs:)
The configuration step is within your job, placed:
- After package manager setup steps (e.g., actions/setup-node, actions/setup-python)
- Before artifact operations (e.g., npm install, docker push, mvn deploy)

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 permissions block (for OIDC authentication)
✅ Workflow completes successfully
✅ At least one artifact is uploaded to Fly Registry

Troubleshooting Steps:

Check workflow logs for Fly action output
Verify permissions block is present at the top level of your workflow:
```
permissions:
  contents: read
  id-token: write
```
Confirm artifact upload succeeded - check package manager logs (npm publish, docker push, etc.)
Ensure workflow completed without errors - check GitHub Actions run status

Verify the Fly action has the correct subdomain URL:

- name: JFrog Fly - Configure all your package managers to work with Fly registry
  uses: jfrog/fly-action@v1
  with:
    url: https://<your-fly-subdomain>.jfrog.io

Can I use the agentic method to configure workflows if I don’t have Cursor or VS Code?

No. The agentic method requires an IDE with Fly MCP integration.

Currently supported IDEs:

Cursor
VS Code with Copilot

Coming soon:

Claude CLI
Gemini CLI

If you don’t have a supported IDE:

Use the manual method to configure your workflows - it’s straightforward:

Open your .github/workflows/*.yml files
Add the configuration snippets (permissions block + Fly action step) - see details
Commit and push

Both methods achieve the same result.

Runtime Deployment

How do I deploy to Kubernetes using Fly?

Fly uses semantic search and your IDE to help you find and deploy the right releases.

Prerequisites:

Ensure Fly Desktop App is running
Ensure your IDE (Cursor or VS Code Copilot) has Fly MCP integrated

To find and deploy a release:

Use natural language prompts in Fly Chat or your IDE:

“Find the release with the payment fix”
“Show me the last successful release”
“Deploy the latest release to production”
“Deploy this release to staging”

What Fly does:

Finds the appropriate release using semantic search
Identifies the correct artifact version from Fly Registry
Provides image references and assists your IDE in deploying to your runtime environment

Note: Fly does not generate Kubernetes manifests. It helps you find the right releases and provides the correct image references for your existing deployment processes.

How do I get a deployment token for my Kubernetes cluster?

To allow your Kubernetes cluster to pull images from Fly Registry:

Click your user avatar (top-right) and select Token Management
Click Create Token
Configure:
- Name: e.g., “k8s-production-readonly”
- Permission: Read-Only
- Expiration: Set appropriate date (e.g., 90 days, or choose based on your security policy)
Click Create and copy the token immediately (it’s shown only once!)
Create Kubernetes Secret:

kubectl create secret docker-registry fly-registry-secret \
  --docker-server=<your-fly-subdomain>.jfrog.io/docker \
  --docker-username=<your-fly-username> \
  --docker-password=<your-fly-token> \
  --namespace=<namespace>

Reference the secret in your deployment manifest:

spec:
  imagePullSecrets:
  - name: fly-registry-secret

Access & Team Management

How do I invite a new user to my team?

Note: Only Admins can invite users.

Navigate to Users & Access in the Fly Web App
Click Invite User
Fill in:
- Email address
- Role (Admin or Developer)
Click Send Invitation

The user receives an email with a signup link. Their status changes from “pending” to “active” upon first login.

How do I generate a new access token?

Click your user avatar (top-right) and select Token Management
Click Create Token
Configure:
- Name: Descriptive name (e.g., “local-dev”, “k8s-production”)
- Permission: Read & Write or Read-Only
- Expiration: Set expiration date
Click Create
Copy the token immediately - it’s shown only once!

Token Use Cases:

Manual configuration - Configure package managers without Desktop App
Runtime environments - Kubernetes clusters pulling images
External systems - CI/CD tools, deployment pipelines
API access - Programmatic access to Fly Registry

Permissions:

Read & Write: Upload and download artifacts
Read-Only: Download artifacts only (recommended for production environments)

How do I revoke a token?

Click your user avatar (top-right) and select Token Management
Find the token you want to revoke in the list
Click Revoke
Confirm the action

The token immediately becomes invalid. Any systems using it will lose access.

Permissions:

Admins can revoke any token
Developers can only revoke tokens they created

What are the permissions for an Admin versus a Developer?

Permission	Admin	Developer
Push/Pull artifacts	✅	✅
View artifacts and releases	✅	✅
Manage workflows	✅	✅
View user list	✅	✅ (read-only)
Create tokens	✅	✅
Revoke own tokens	✅	✅ (only tokens they created)
Invite users	✅	❌
Update user roles	✅	❌
Delete users	✅	❌
Revoke others’ tokens	✅	❌
Manage team settings	✅	❌

Note: The system ensures at least one Admin always exists.

Additional Questions

Where can I find the JFrog Fly documentation?

The complete JFrog Fly documentation is available at docs.fly.jfrog.ai.

How do I download an npm package in my CI pipeline?

If your CI workflow has the Fly action configured, npm automatically uses the Fly Registry:

- name: JFrog Fly - Set as Default Registry for All Package Managers
  uses: jfrog/fly-action@v1
  with:
    url: https://<your-fly-subdomain>.jfrog.io

- name: Install dependencies
  run: npm install

The npm install command automatically pulls from Fly Registry - both your uploaded artifacts and public dependencies.

What are the specific commands for uploading a Maven artifact?

With Fly Desktop App running:

mvn clean deploy

In CI with Fly action configured:

- name: JFrog Fly - Set as Default Registry for All Package Managers
  uses: jfrog/fly-action@v1
  with:
    url: https://<your-fly-subdomain>.jfrog.io

- name: Deploy artifacts
  run: mvn clean deploy

How do I find a specific artifact?

Use Fly Chat or search in the Web App:

In Fly Chat:

“Find the latest payment-service Docker image”
“Show me all npm packages uploaded this week”
“Search for artifacts from the API repository”

In Web App:

Navigate to Artifacts
Use the search bar to filter by name
Apply filters (type, date, repository)
Click artifact to see all versions

How do I view all artifacts from a single Git repository?

Navigate to Git Repositories in the Fly Web App
Click on the repository you want to view
Click the Artifacts tab

This shows all uploaded artifacts from that specific repository.

How do I see all the releases from a specific repository?

Navigate to Git Repositories in the Fly Web App
Click on the repository
Click the Releases tab
View all releases from successful CI/CD runs

You can also use semantic search in Fly Chat or your IDE to find specific releases:

“Show me the latest release from payment-service”
“Find releases from last week”

What is a release?

A Release is a record automatically created every time a configured GitHub Actions workflow successfully uploads one or more artifacts to Fly Registry.

Each release includes:

AI-generated summary of changes (features, bug fixes, updates)
List of uploaded artifacts (packages pushed to Fly)
List of public dependencies consumed
Related commits and pull requests
Link to GitHub Actions workflow
Complete provenance information

Releases are searchable using natural language queries via Fly Chat or your IDE.

Can I search for releases using natural language?

Yes! This is one of Fly’s most powerful features - Semantic Release Search.

In Fly Chat:

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

In your IDE (with Fly MCP): Add “Fly release” to help focus the search:

“Find the Fly release that broke production”
“Show me the latest stable Fly release”
“Find the Fly release with Docker image updates”

Fly searches through the AI-generated summaries, commits, PRs, and metadata to find exactly what you’re looking for.

How do I configure a specific workflow file?

You can configure individual workflow files using Fly MCP:

Open your IDE (with Fly Desktop App running)
Open the workflow file you want to configure
Use a prompt:
- “Configure this workflow for Fly Registry”
- “Configure this workflow to work with Fly Registry”

Fly MCP automatically adds the necessary configuration snippet and permissions to that specific workflow file.

Alternatively, you can manually add the Fly action to the workflow file.

What happens to public dependencies I download?

When you download a public dependency (like express from npm or requests from PyPI):

Fly checks if it’s in your uploaded artifacts first
If not found, Fly fetches it from the public registry
Fly caches the public dependency for faster future access
The cached dependency is available to your entire team

This provides:

Faster downloads (cached packages)
Reliability (available even if public registry is down)
Unified access (all packages through one registry)

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 App
Browse Documentation → - Explore the detailed sections of this guide
Contact Support → - Reach out to JFrog support for beta assistance