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 App - Local development setup
  • Package Management - Uploading and downloading artifacts
  • Automated Workflows - Configuring CI/CD workflows
  • Runtime Environments - Deploying, tracking, and managing runtime environments
  • Team Members & Tokens - Managing users and tokens

Onboarding & Setup

JFrog Fly App

Package Management

Automated Workflows

Runtime Environments

Team Members & Tokens

Onboarding & Setup

How do I create a new account?

  1. Request beta access at jfrog.com/fly. Once approved, you’ll receive an email invitation.
  2. Click the link in the email – you’ll be redirected to the product page.
  3. Download the Fly App by clicking the download button, or copy the curl command and paste it in your coding agent or terminal.
  4. Sign up with GitHub, Google, or Email + Password, then pick a team name. This becomes your private Fly Registry at <your-team>.jfrog.io.

The first user to create the account becomes the team Admin with full permissions.

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

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?

Ask your coding agent: “Start working with Fly.” Fly walks you through connecting 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.

You can also connect your GitHub organization from Fly Web.

To manage your organizations and repositories later:

  1. Navigate to Git Repositories in Fly Web
  2. Click Manage Org & Repositories
  3. 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 App

How do I install the Fly App?

  1. Download the Fly App by clicking the download button on the product page, or copy the curl command and paste it in your coding agent or terminal:
# macOS / Linux
curl -fsSL https://fly.jfrog.ai/download/desktop | bash

# Windows (PowerShell)
irm https://fly.jfrog.ai/download/desktop | iex
  1. Grant the necessary permissions when prompted.
  2. The app automatically detects your package managers and connects your coding agent to work with Fly.

Currently supported: macOS and Windows

How do I get my local environment configured?

The Fly App automates your local environment setup:

  1. Install and log in to the Fly App
  2. App automatically detects your local package managers (npm, pip, docker, helm, maven, etc.) and Coding Agents (Cursor, Copilot, Claude Code, OpenCode)
  3. 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 coding agent for AI-powered workflows

You can also select a default coding agent 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 with your coding agent 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, Copilot, Claude Code, or OpenCode through the Fly App.

What Coding Agents are supported?

Currently supported:

  • Cursor
  • Copilot
  • Claude Code
  • OpenCode

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

Is Fly available on Windows or Linux?

Currently: Fly App supports macOS and Windows.

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

Package Management

How do I upload an artifact?

Ask your coding agent:

“Publish this npm package to Fly”

Fly handles everything. Your package goes directly to your private Fly Registry. No configuration files, no tokens. The Fly Desktop App already configured your local package managers on install.

Using terminal commands instead? Make sure your Fly App is installed and your package managers are configured, and you’re all set. Your regular commands are already pointing to Fly:

npm publish
twine upload dist/*
mvn deploy

For Docker, include your Fly subdomain in the image path:

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

Manual with Token

For environments without the Fly App, generate an access token in Fly Web and configure your package manager manually using your registry path.

How do I upload and download a Docker image locally?

Ask your coding agent:

“Push this Docker image to Fly”

or

“Pull my-app:latest from Fly”

Fly handles everything including adding the correct subdomain to the image path automatically.

Using terminal commands instead? Make sure your Fly App is installed and Docker is configured. Include your Fly subdomain in the image path:

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

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

Manual with Token

  1. Generate an access token in Fly Web (Read & Write permission)
  2. Login to the Fly Docker registry:
docker login <your-fly-subdomain>.jfrog.io -u <your-fly-username> -p <your-fly-token>
  1. Use standard Docker commands with your Fly subdomain in the image path.

How do I upload and download an npm package?

Ask your coding agent:

“Publish this npm package to Fly”

or

“Install my-private-package from Fly”

Fly handles everything. No configuration files, no tokens.

Using terminal commands instead? Make sure your Fly App is installed and npm is configured, and you’re all set:

# Upload
npm publish

# Download
npm install <package-name>

Manual with Token

  1. Generate an access token in Fly Web (Read & Write permission)
  2. 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>
  1. Use standard npm commands.

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

  1. Generate an access token in the Fly Web (Read & Write permission)

  2. Create or update ~/.pypirc file:

[distutils]
index-servers = pypi

[pypi]
repository = https://<your-fly-subdomain>.jfrog.io/artifactory/api/pypi/pypi
username = <your-fly-username>
password = <your-fly-token>
  1. Build your package:
python -m build
  1. Upload with twine:
twine upload dist/*

What public registries does Fly proxy?

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

TechnologyPublic Registry
npmhttps://registry.npmjs.org
piphttps://files.pythonhosted.org (PyPI)
Mavenhttps://repo1.maven.org/maven2 (Maven Central)
Dockerhttps://registry-1.docker.io (DockerHub)
Helmhttps://registry-1.docker.io (DockerHub)
Gohttps://proxy.golang.org
NuGethttps://www.nuget.org
Gradlehttps://repo1.maven.org/maven2 (Maven Central)

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.

Simply prompt your coding agent:

“Configure my workflows with Fly”

Fly scans your .github/workflows/*.yml files and opens a pull request with the required changes already applied. Review the PR, merge it, and you’re done.

Once merged, every push publishes your artifacts to Fly Registry and creates a release with full traceability. Find any release by what it contains, not just version numbers. No tokens, no secrets stored in GitHub.

What Fly adds to each workflow file (via PR):

OIDC permissions for secure, token-free authentication:

permissions:
  contents: read
  id-token: write

Fly action to configure your package managers on the CI runner:

- name: JFrog Fly - Configure all your package managers to work with Fly registry
  uses: jfrog/fly-action@v1

For Docker and Helm, the Fly action also exports your Fly Registry subdomain as the FLY_REGISTRY_SUBDOMAIN environment variable (e.g., acmecorp.jfrog.io). Use it in subsequent steps: ${{ env.FLY_REGISTRY_SUBDOMAIN }}/docker/my-app:tag

Prefer to Configure Manually?

Add the same two snippets to your .github/workflows/*.yml files directly.

Place the permissions block at the top level of your workflow file, after on: and before jobs:.

Place the Fly action step within your job, after any package manager setup steps (like actions/setup-node) and before artifact operations (like npm publish or docker push).

Why isn’t my workflow creating releases?

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

  1. ✅ Workflow has the Fly action configured
  2. ✅ Workflow has the required permissions block (for OIDC authentication)
  3. ✅ Workflow completes successfully
  4. ✅ At least one artifact is uploaded to Fly Registry

Troubleshooting Steps:

  1. Check workflow logs for Fly action output
  2. Verify permissions block is present at the top level of your workflow:
    permissions:
  contents: read
  id-token: write
  3. Confirm artifact upload succeeded - check package manager logs (npm publish, docker push, etc.)
  4. Ensure workflow completed without errors - check GitHub Actions run status
  5. Verify the Fly action is present:
    - name: JFrog Fly - Configure all your package managers to work with Fly registry
  uses: jfrog/fly-action@v1

Can I use the Coding Agent method to configure workflows?

The Coding Agent method requires Fly MCP integration.

Currently supported:

  • Cursor
  • Copilot
  • Claude Code
  • OpenCode

If you don’t have a supported Coding Agent:

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

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

Both methods achieve the same result.

Runtime Environments

How do I deploy to Kubernetes using Fly?

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

Prerequisites:

  1. Ensure Fly App is running
  2. Ensure your Coding Agent (Cursor, Copilot, Claude Code, or OpenCode) has Fly MCP integrated

To find and deploy a release:

Use natural language prompts in Fly Chat or your coding agent:

“Find the release with the payment fix”

“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 coding agent 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 create an environment?

From your coding agent:

“Create a new environment called prod-us-east”

Or from Fly Web:

  1. Navigate to Runtime Environments
  2. Click Create Environment
  3. Provide a name and optional description

After creation, Fly suggests generating a token to connect the environment right away.

How do I connect my environment to Fly?

Generate an environment-scoped token (from your coding agent, during environment creation, or from the environment profile in Fly Web), then apply the image pull secret to your K8s namespace:

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

Once applied, Fly tracks every image pull against the environment.

How do I check if my fix is deployed to production?

Ask Fly from your coding agent or Fly Chat:

“Is the fix for the login timeout issue deployed to production?”

“Is PR #278 live in staging?”

Fly searches the current release and recent release history to tell you which release contains the fix, when it was deployed, and which environments have it.

How do I compare what’s running in staging vs production?

Ask Fly from your coding agent or Fly Chat:

“Compare staging vs production”

Fly shows a side-by-side comparison: which releases are in sync, which PRs and fixes exist in one but not the other, and the version gap between them.

What happens when I delete an environment?

Deleting an environment requires explicit confirmation. Once deleted, all associated tokens are automatically revoked and the environment will no longer track consumption. Historical data is removed.

Team Members & Tokens

How do I invite a new user to my team?

Note: Only Admins can invite users.

  1. Navigate to Team Members in the Fly Web
  2. Click Invite User
  3. Fill in:
    • Email address
    • Role (Admin or Developer)
  4. 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?

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

Token Use Cases:

  • Manual configuration - Configure package managers without Fly 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?

  1. Click your user avatar (top-right) and select Token Management
  2. Find the token you want to revoke in the list
  3. Click Revoke
  4. 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?

PermissionAdminDeveloper
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 - Configure all your package managers to work with Fly registry
  uses: jfrog/fly-action@v1

- 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 App running:

mvn clean deploy

In CI with Fly action configured:

- name: JFrog Fly - Configure all your package managers to work with Fly registry
  uses: jfrog/fly-action@v1

- 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:

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

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

  1. Navigate to Git Repositories in the Fly Web
  2. Click on the repository you want to view
  3. Click the Artifacts tab

This shows all uploaded artifacts from that specific repository.

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

  1. Navigate to Git Repositories in the Fly Web
  2. Click on the repository
  3. Click the Releases tab
  4. View all releases from successful CI/CD runs

If your repository has more than one configured workflow, use the Workflow Selector at the top of the page to focus on a specific workflow or view all workflows together.

You can also use semantic search in Fly Chat or your coding agent 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:

  • Release Title: a short, descriptive name with a small icon. Fly generates this automatically. You can edit it at any time.
  • Release Description: a one-line summary shown as a hover preview in the release list. Fly generates this automatically. You can edit it at any time.
  • Release Summary: a full, structured breakdown of what changed, shown on the release detail page.
  • Triggered By: the GitHub user who ran the workflow.
  • Artifacts: all packages and images produced, with their types and versions.
  • Commits and Pull Requests: the Git changes included, with links to GitHub.
  • Workflow: the GitHub Actions workflow that produced the release, with a link to the run.
  • Generation Time: when the release was created.
  • Environment Badges: colored badges showing which environments this release is currently running in.

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

Can I edit a release title or description?

Yes. Open any release’s detail page and click on the Title or Description to edit it. Your changes are saved immediately and reflected in semantic search, so future queries will use your updated text to find the release.

Can I search for releases using natural language?

Yes. There are two ways to search releases with natural language:

Chat Search (within the release list): Type a question directly in the release list page and Fly filters the list to show the relevant releases. For example: “Which releases contain changes to the auth module?”

Fly Chat and your coding agent (across all releases): Ask broader questions from anywhere in Fly Chat or your coding agent (with Fly MCP). Add “Fly release” in your coding agent query to help focus the search.

  • “Find the release where I fixed the login bug”
  • “Show me Jon’s last deployment”
  • “Releases from last week with API changes”
  • “Find the Fly release that broke production”
  • “Find the Fly release with Docker image updates”

Fly searches through release titles, descriptions, 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:

  1. Open the workflow file you want to configure in your coding agent
  2. Simply prompt your coding agent:
    • “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):

  1. Fly checks if it’s in your uploaded artifacts first
  2. If not found, Fly fetches it from the public registry
  3. Fly caches the public dependency for faster future access
  4. 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:

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