Artifact Repositories

Repositories hold collections of files and metadata also commonly referred to as packages, artifacts, or images.

Dist offers Container & Maven repositories.

Role-based access control

Dist only supports private artifact repositories and all access is controlled through role-based authorizations.

There are four repositories roles (which are distinct from organization roles):

  • Administrator
  • Developer
  • Uploader
  • Reader

Each repository has its own set of authorizations so that users and groups can be granted different roles for each repository.

Tip

We recommend granting repository roles to groups rather than to users directly. Using groups makes it easy to add and remove access based on a function rather than identity.

Example: suppose ACME Corp has an Android developer named Fred and two Maven repositories: acme-app and acme-shared-libraries.

Fred might be granted Developer access to acme-app and Reader access to acme-shared-libraries. However, we would recommend creating an Android Developers group, adding Fred to that group, and granting access to the group instead of directly to Fred.

Doing it this way makes it easy to grant access to new Android developers by simply adding them to the group. Similarly, if Fred changes roles he could be removed from the group instead of individually modifying Fred's access to each repository.

Repository roles & permissions

Permission Administrator Developer Uploader Reader
Upload artifacts ✔ ✔ ✔
Download artifacts ✔ ✔ ✔ ✔
List artifacts ✔ ✔
Grant and revoke repository roles ✔
View assigned repository roles ✔ ✔
Edit repository details ✔
Delete repositories ✔

As a convenience the Uploader role includes the Download artifacts permission. This is required by many repository tools to update metadata or check for the existence of artifacts.

Access Tokens

Access tokens are used to authenticate access to repositories and are managed from the Settings section of your organization.

Access tokens are unique to each user and inherit that user's repository roles and associated permissions. Each access token is also scoped, allowing each token's effective roles and permissions to be further limited.

An access token's scope is defined by its:

  • Coverage: All repositories, or selected repositories; and
  • Permitted roles: Zero or more repository roles.

The effective permissions of an access token is the minimum permissions granted by both the user's repository roles and the access token's scope.

For example, consider the following configuration:

  • Alice has the following repository roles:
    • Administrator access to the acme-app repository; and
    • Developer access to the acme-libs repository.
  • Alice has two access tokens:
    • Access token dev scoped to Reader for the acme-libs repository; and
    • Access token publish scoped to Uploader across all repositories.

Given the above configuration the following will be true:

  • Alice's dev access token will only have permission to Download artifacts from the acme-libs repository. It will have no permissions for the acme-apps repository.
  • Alice's publish access token will only have permission to Upload artifacts to both acme-app and acme-libs repository. It will have no other permissions to either repository.