Skip to main content

Migrate from Satis

Move one application's packages to Package Broker while keeping its Satis repository available for rollback. This how-to uses manual source creation: two Git repositories and one Composer repository. Repeat the rehearsal for each application before changing its production configuration.

Before you start​

Have Composer 2, a running broker, an organization admin session, the application's composer.json and composer.lock, and access to the original package repositories. Use the broker UI at https://<broker-host>/_pb/ui; replace <broker-host> with your broker's HTTPS host, including a nondefault port. An organization admin can create the project, register package names and enable sources.

For the Git over HTTP(S) example below, use Node and confirm that Repository provider offers Git over HTTP(S). Workers serves GitHub sources instead; select GitHub and supply its repository and authentication settings if both packages live there. For an SSH (git@) URL, use an HTTPS clone URL with an origin credential on Node, or a GitHub source on Workers. Git over SSH is not served as installable distributions. The provider list also depends on the providers composed into your broker build.

Keep Satis metadata, archives, its existing credentials and your pre-migration application files until rollback has been rehearsed. Record the package versions, source commit references and archive URLs in the original lock file. Source creation does not transfer historical archives that are no longer available from the original repositories.

Map the configuration​

Compare your configuration with the Satis configuration documentation. The table maps selection and storage settings; it does not promise identical package sets or version filtering.

Satis inputPackage Broker destinationWhat to review
repositories with type: vcs or gitOne Composer Git repository source for each repository.Select a served provider and the tags or branches to import.
repositories with type: composerA Composer repository source with an explicit package selection.Use the original repository URL, rather than the Satis output URL, when retiring Satis.
requirePackage names or patterns for a Composer repository source; tag and branch selection for Git sources.No equivalent for Satis version constraints in source selection. Keep application version constraints in composer.json and compare resolved versions.
require-allNo equivalent switch across all sources.Enumerate the packages or reviewed patterns for each Composer source; an empty selection selects no packages. Git sources select tags and named branches.
archiveNo equivalent Satis archive configuration object.Broker archive storage and source retention are configured separately; existing Satis archives are not copied by these steps.
configNo equivalent bulk configuration object.Review each Composer setting. Put source credentials in Set credential and application settings in the application's composer.json; do not paste Satis configuration into a source.
repositories with type: pathNo equivalent local-directory source.Make the package available through a served Git or Composer repository source before migrating.
repositories with type: artifactNo equivalent archive-directory source.Publish the required versions through a served source; this procedure does not import a directory of archives.
repositories with type: packageNo equivalent inline package-definition source.Provide the metadata and archives through a Composer repository source, or use a served Git source.
require-dependenciesNo equivalent dependency-expansion switch.Inventory transitive dependencies in the whole application lock file and explicitly select any packages the broker must serve.

For example, start with this inventory in satis.json. Replace the example URLs and package names with repositories you control. The two Git repositories must contain the corresponding Composer package names and the tags required by your application; the Composer repository must serve example/dependency. All three packages must already be dependencies in the rehearsal application and present in its lock file. Replace these example package names in every command below.

{
"name": "Migration rehearsal",
"homepage": "https://satis.example.com",
"repositories": [
{ "type": "vcs", "url": "https://git.example.com/example/library-a.git" },
{ "type": "vcs", "url": "https://git.example.com/example/library-b.git" },
{ "type": "composer", "url": "https://composer.example.com" }
],
"require": {
"example/library-a": "*",
"example/library-b": "*",
"example/dependency": "*"
},
"require-all": false
}

Recreate the sources​

  1. In Projects, expand New project, set Project name to Satis migration and Slug to migration-satis, and leave Maximum token scope at read. Choose Create project and leave the application's production repository configuration unchanged.
  2. Switch the UI scope to Organization, open Sources and choose Add source. Set Ecosystem to Composer and Source type to Git repository. Name the first source migration-library-a, select Git over HTTP(S), and enter the first Git URL from the inventory. Under Advanced settings, keep Import tags selected; leave Branches to import empty if your application uses only tags. Repeat for migration-library-b and the second Git URL.
  3. Add migration-dependency with ecosystem Composer, source type Composer repository, repository URL https://composer.example.com, and example/dependency in Package names (one per line). Leave package patterns empty for this rehearsal.
  4. For each private source, choose More → Set credential, select the credential kind supported by that origin, and type the origin credential into the write-only Set credential dialog. Choose Save credential. Reauthenticate if requested. Use URLs without embedded credentials. If archives use another host, review Additional archive hosts before adding it: the source credential is also sent to those hosts.
  5. In organization scope, open More → Registered names on each source. Use Add name to register only example/library-a, example/library-b or example/dependency on its corresponding source. Choose Enable, then Sync now. Wait for a successful sync; a queued request alone does not prove the versions were imported.
  6. Switch to project migration-satis, open Sources, and Attach these three organization sources. Review Source order if another source supplies the same package name, then Save source order. Open Packages and compare the required versions and revisions with your inventory.

Recreate access and credentials​

Select project migration-satis in the UI scope, open Access, and review the intended consumers. For a read-only consumer, the recommended built-in role is Project Auditor, the narrowest built-in project role without write access. It reads packages, sources, grants (including e-mail addresses), project tokens and the audit log. If the consumer should only read packages, an organization admin can create a narrower custom project role with only project:read and project:packages:read under Organization → Access → Roles → New role, and use its ID for the grant instead. To find the chosen role's raw ID, switch to Organization → Access → Roles and copy the ID displayed beneath its name in the Role column. Return to the project scope, open Access → New grant, paste that ID into Role ID, enter the subject, and choose Create grant. For a group subject, enter the identity provider as well. Add only the grants needed for this project and test with the consumer's identity.

Each consumer or CI environment needs its own broker identity and token, or its own service-principal project token. This is the broker counterpart of a per-customer Satis token. Grant each consumer identity access before it issues its personal token; do not distribute the administrator's personal token to consumers. See the token table in the access model for token selection.

For a personal token, sign in as that consumer, open Tokens, choose My personal tokens under Token list, and expand Issue token. Set Scope to Read, choose Selected projects under Projects, and enter only this project's ID in Selected project IDs. Find it in the Project ID column of Projects; use the ID, not the slug migration-satis. For CI using a service principal, you need an existing principal for this project and a project-scoped token. An administrator can create the principal under Tokens → Service principals, supplying this project's ID and the required permissions. In project scope, choose Project tokens under Token list, expand Issue token, select Read and that principal under Service principal, and issue the token. Follow Composer credentials to supply the token through an uncommitted auth.json file or a secret COMPOSER_AUTH environment variable. Retain the original Satis authentication for rollback. Keep tokens out of repository URLs and shell command literals.

Rehearse the switch​

Use a disposable copy of the application, including its lock file. Keep its original files separately for rollback. In this sample, the existing Satis entry is the first repository and looks like this; preserve any other entries and their order in your own application.

{
"repositories": [
{
"name": "satis",
"type": "composer",
"url": "https://satis.example.com"
}
]
}

Replace that entry in the rehearsal copy with the following. Use your broker host; keep this entry ahead of other repositories that could supply the same private package names. Do not leave a direct Git or Satis entry ahead of it.

{
"repositories": [
{
"name": "broker",
"type": "composer",
"url": "https://<broker-host>/migration-satis"
}
]
}

Run a resolution dry run from the rehearsal application's directory, naming all three packages. It may fetch metadata but should not change the lock file or install packages. Review the proposed versions against the original lock file. Stop if a required version is missing or an unexpected package changes.

composer update 'example/library-a' 'example/library-b' 'example/dependency' --dry-run --no-plugins --no-scripts

Switch one application​

In the rehearsal copy, resolve the same package set and install it. A targeted update can change the named packages and dependencies within your constraints; inspect the entire lock-file diff before accepting it. Changing the repository URL alone leaves existing lock-file distribution URLs intact.

composer update 'example/library-a' 'example/library-b' 'example/dependency' --no-plugins --no-scripts

Require exit code 0 from the update. Check that the three packages' distribution URLs in composer.lock point to your broker and that their references match the reviewed versions. Search the whole lock file for the old Satis host, including source, distribution and notification URLs. Replace satis.example.com below with the old host from your inventory; repeat for any other host you plan to retire.

grep -cF 'satis.example.com' composer.lock

The count must be 0 (grep exits 1 for zero matches). Any match blocks retirement: migrate the remaining packages or URLs and repeat the check. Do not retire Satis while any application's lock file still refers to it.

Now remove the installed packages from the configured vendor-dir (which may differ from vendor) and use a new empty Composer cache before installing the reviewed lock file. Remove the temporary cache after the install, preserving its exit status:

rm -rf -- "$(composer config vendor-dir)"
cutover_cache=$(mktemp -d)
install_status=0
COMPOSER_CACHE_DIR="$cutover_cache" composer install -v --no-plugins --no-scripts || install_status=$?
rm -rf "$cutover_cache"
test "$install_status" -eq 0

Require install_status to be 0. In the composer install -v output, look for Downloading and Extracting archive for each sample package, and confirm its distribution URL in the reviewed lock file points to the broker. There must be no Cloning or Now trying to download from source line for those packages; an install from source does not verify broker archive serving. Run your application's usual checks. Review any required Composer plugins or scripts before enabling them.

Apply the reviewed repository entry and lock file to just this application. Supply broker credentials separately in developer and CI environments, and perform the same fresh install there. Keep Satis running until that application and its CI pass. Follow the GitHub Actions or GitLab CI recipe for CI credential handling.

Roll back​

Restore the pre-migration composer.json and composer.lock together. For the sample, the exact repository change is to replace the broker object above with this original object, in the same position; replace https://satis.example.com with the original Satis URL you recorded. Remove the broker entry if you added it separately. Restore any other repository and Packagist settings changed during the rehearsal.

{
"name": "satis",
"type": "composer",
"url": "https://satis.example.com"
}

Restore the original Composer authentication from its protected environment or file, then install the original lock file with the application's normal install command, with plugins and scripts enabled. The example uses composer install; keep any flags your application normally requires and the empty-cache environment setting. Remove the configured vendor-dir, then clean up the temporary cache after the install while preserving its exit status:

rm -rf -- "$(composer config vendor-dir)"
rollback_cache=$(mktemp -d)
install_status=0
COMPOSER_CACHE_DIR="$rollback_cache" composer install || install_status=$?
rm -rf "$rollback_cache"
test "$install_status" -eq 0

Require install_status to be 0 and confirm the old versions install from Satis before revoking the broker token issued for this migration. Restoring only the Satis URL while retaining the broker lock file is insufficient: that lock file can still point at broker archives.