Read private packages.

In every workspace, an Admin can save a GitHub Packages credential in Setup for package restores. Connecting a repo through the GitHub App supplies no package credential.

Supported registries and packages

GitHub Packages NuGet feeds at nuget.pkg.github.com and scoped npm packages at npm.pkg.github.com are supported. Maven and Gradle can read Java artifacts at maven.pkg.github.com; RubyGems can read gems at rubygems.pkg.github.com.

Azure Artifacts, self-hosted feeds and container registries are not supported. Public package downloads use your workspace's network access settings. Package publication is not supported.

Access you need

GitHub Packages requires a personal access token (classic) for these connections. Fine-grained personal access tokens and GitHub App installation tokens are not supported. The GITHUB_TOKEN exception applies to GitHub Actions workflows, not Perfloop Sessions.

A classic PAT cannot be scoped to one organization or package. Use a dedicated machine-user account with read access only to the packages needed for these builds. Review its organization and team memberships, inherited repository permissions, and access to internal packages. Explicit package grants do not remove access the account gets through those other paths.

Setup

1 · grant package access

NuGet, npm and RubyGems packages can have their own access permissions. For each required package, open its settings in GitHub. Under Manage access, select Invite teams or people, add the machine-user account, and give it the Read role. The account must also be an organization member to read private or internal organization packages. Check the package's visibility and inherited permissions before relying on an explicit grant.

Maven packages inherit their repository's permissions. Give the machine-user account read access to each repository that owns the packages it needs.

2 · create a read-only token

Sign in as the machine user. Open Settings → Developer settings → Personal access tokens → Tokens (classic) and generate a token. Select only read:packages. Do not add repo, write, or delete scopes. Set an expiration date. If the organization uses SAML SSO, authorize the token for that organization through Configure SSO.

Keep the token in your secret store. Enter it only in Setup, never in chat, source files, package-manager configuration, or an MCP call.

3 · save the feed in Perfloop

As a workspace Admin, open Setup → Network access → Private registries. Under Supported registries, find the GitHub Packages row for your package type and select Add feed. Maven and Gradle use the row marked Maven / Gradle. Enter the package owner in Organization or user for NuGet, Maven, Gradle or RubyGems. Maven and Gradle require the owner in lowercase; leave their Repository field at * for all that owner's repos, or name one repo. npm has no owner field. Setup shows the feed address it saves. Enter the machine user's GitHub login in GitHub username and its token in Classic personal access token. Select Save and test.

The saved feed permits HTTPS package reads across eligible Sessions in the workspace, not only one repo. It grants no package publication. You do not need a separate destination Allow for that feed.

NuGet source

For NuGet, keep the package source in your repo's NuGet.Config. Use the saved feed address exactly, including the owner's capitalization, and append index.json, for example https://nuget.pkg.github.com/YOUR-ORG/index.json. Keep credentials out of that file. Setup supplies the saved credential when Perfloop restores packages from this feed.

npm source

For npm, keep your package scope's registry in the repo's .npmrc, for example @your-org:registry=https://npm.pkg.github.com. Replace your-org with the lowercase GitHub account that owns your packages. Keep credentials out of that file. The saved npm root covers every package namespace the account can read; a URL path cannot restrict it to one organization.

The default public destinations include https://repo.yarnpkg.com/ for Yarn and https://registry.yarnpkg.com/yarn/ for the Yarn 1 package. Node downloads use https://nodejs.org/dist/. An Admin can remove these destinations in Setup → Network access → Public destinations. Other package sources need separate network access.

Maven and Gradle source

Keep the repository URL in your repo's pom.xml for Maven, or build.gradle or build.gradle.kts for Gradle. For one repo, use https://maven.pkg.github.com/your-org/your-repo. Replace your-org and your-repo with the lowercase GitHub owner and repository names. If you saved an all-repos feed, you can instead use https://maven.pkg.github.com/your-org/*. Keep the asterisk literal; do not encode it as %2A. Keep credentials out of the POM, Maven settings and Gradle files.

Maven Central defaults include https://repo.maven.apache.org/ and the alternate artifact tree https://repo1.maven.org/maven2/. An Admin can remove either destination in Setup → Network access → Public destinations. Removing one does not remove the other.

Use your repo's Gradle wrapper. The default public destinations include https://services.gradle.org/distributions/ and https://downloads.gradle.org/distributions/. An Admin can remove these destinations. If a download is blocked, check Setup → Network access → Public destinations. Other repositories, including the Gradle Plugin Portal, need separate network access.

RubyGems source

Use your saved feed address as the RubyGems source, for example https://rubygems.pkg.github.com/YOUR-ORG/. Replace YOUR-ORG with the package owner. Keep the username and token out of the URL and your repo's package configuration.

Check the connection

Saving a GitHub Packages feed also permits HTTPS downloads from *.blob.core.windows.net, pkg-npm.githubusercontent.com and github-registry-files.githubusercontent.com. You do not need to allow those download hosts separately. The wildcard covers subdomains across Azure storage accounts, not only the account GitHub uses. Download addresses can carry data out. Perfloop sends no registry token or cookies to those hosts. Other download hosts still need separate network access.

Saving alone does not check whether GitHub accepts the credential, so Setup then makes one test read of the feed and shows the result on the saved row: Read OK, Token rejected (401), Access refused (403), Unreachable or the HTTP status, with when it happened. Later, the row can also show a result recorded during a restore, with its time. It does not show every read. A failed test leaves the feed saved. Select Replace token or Test again on the row after you fix the account or token. Replacing the token clears its previous status and tests the new one.

A Maven feed's test can show 404 because GitHub provides no repository index at that address. Check a restore of a package the account can read before changing a Maven credential for that result.

A successful response does not prove a package restore. A 401 or 403 does not identify the cause. Check the account's package access, token scope, expiry, and SSO authorization. Replace the saved credential if needed. Authentication errors do not pause work automatically.

Set up with your coding agent

Ask your agent to call setup with section: "private_registries". It returns saved feeds and entry links. Your agent fills the selected link's username and any owner or repository fields, then gives you the link. Open it, sign in as a workspace Admin, and enter the token in Setup. The link contains no token and grants no access. After saving, wait for Setup's automatic check to finish, then ask your agent to read Setup for the result. To test again, ask it to call testPrivateRegistry with the feed's id.

Data Perfloop reads and keeps

Perfloop reads feed metadata and package content within the saved prefix, and packages from the download hosts above. Those bytes are available to its work and can remain in build caches. Credentials are stored encrypted and scoped to the workspace and the saved feed address. Another workspace cannot use your saved credential. Perfloop does not put the token in the build environment or package-manager configuration, and never displays a saved token again. See Security for data handling.

Replace a token

Before expiry, create a replacement token with the same limited permissions and required SSO authorization. In Setup, select Manage, then Replace token on the saved feed. Enter the username and replacement token, then select Replace and test. Revoke the replaced token in GitHub too. To change the feed address, remove the feed and add another.

Through MCP, ask your agent for the saved feed's replaceURL from Setup. It opens the same replacement form. Check that the feed address is the one for your token before you enter it. Never enter the token in the conversation.

Remove access

Select Manage, then Remove feed on the saved feed and confirm. This removes that credential and prefix grant. Removing the last GitHub Packages feed also removes the download access described above. Separately saved network destinations remain in place; remove those in Public destinations if you no longer need them. A shorter saved parent prefix can still provide feed access. Requests already in progress can finish, and downloaded packages remain in caches. Revoke the token in GitHub to remove its upstream access too.

Your agent can also call removePrivateRegistry with the saved feed's id. Read Setup again to confirm that the feed is gone.

Security questions: security@perfloop.ai