Aug 13: Context layer webinar
Chalk home page
  1. Infrastructure
  2. Artifact Repository

Chalk can resolve Python packages from one or more private indexes alongside PyPI. You configure them in Infrastructure > Artifact repositories. Each index is rendered into the builder’s uv.toml as an [[index]] block. PyPI is always emitted first; the global prefer-private option controls whether PyPI is marked as the fallback (default = true) so private indexes are searched first.

Three index kinds are supported:

  • AWS CodeArtifact: An AWS CodeArtifact repository. Chalk authenticates using a Chalk IAM principal that you grant read access to.
  • Google Artifact Registry (GAR): A GAR Python repository. Chalk authenticates with the management service account configured for your environment.
  • Preauthenticated: Any pip-compatible index URL whose full authenticated URL is stored in your team’s secret store. Chalk reads the URL from the secret at build time and uses it as-is.

​
AWS CodeArtifact

Chalk supports downloading Python packages from private AWS CodeArtifact repositories. To use this feature, give a Chalk IAM principal access to your repository so that Chalk can authenticate with the CodeArtifact pip registry.

​
Grant access to Chalk

Chalk authenticates to your CodeArtifact repository using an IAM principal. You can view the IAM principal in your team’s settings page. The principal looks like this:

arn:aws:iam::***********:role/chalk-*********

After you have the IAM principal ARN, grant the following permissions to the principal:

codeartifact:DescribePackageVersion
codeartifact:DescribeRepository
codeartifact:GetPackageVersionReadme
codeartifact:GetRepositoryEndpoint
codeartifact:ListPackages
codeartifact:ListPackageVersions
codeartifact:ListPackageVersionAssets
codeartifact:ListPackageVersionDependencies
codeartifact:ReadFromRepository

These permissions are derived from AWS’s instructions. They grant Chalk read access to the repository, but not write access. Here is an example IAM policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CodeArtifactPermissions",
      "Effect": "Allow",
      "Action": [
        "codeartifact:DescribePackageVersion",
        "codeartifact:DescribeRepository",
        "codeartifact:GetPackageVersionReadme",
        "codeartifact:GetRepositoryEndpoint",
        "codeartifact:ListPackages",
        "codeartifact:ListPackageVersions",
        "codeartifact:ListPackageVersionAssets",
        "codeartifact:ListPackageVersionDependencies",
        "codeartifact:ReadFromRepository"
      ],
      "Principal": {
          "AWS": "arn:aws:iam::***********:role/chalk-*********"
       },
      "Resource": "*"
    }
  ]
}

After you create this policy, attach it to your repository with the following example command:

aws codeartifact put-repository-permissions-policy --domain my_domain --domain-owner 111122223333 \
          --repository my_repo --policy-document file:///PATH/TO/policy.json

Or go to Infrastructure > Artifact repositories and fill in the necessary fields:

​
Google Artifact Registry

Chalk supports downloading Python packages from private Google Artifact Registry (GAR) Python repositories. Chalk authenticates using the management service account configured for your GCP environment, so no per-repo credentials need to be supplied.

​
Grant access to Chalk

Grant the management service account read access to the Artifact Registry repository. The roles/artifactregistry.reader role is sufficient. For example, run:

gcloud artifacts repositories add-iam-policy-binding my_repo \
  --location=us-central1 \
  --member="serviceAccount:chalk-management@my-project.iam.gserviceaccount.com" \
  --role="roles/artifactregistry.reader"

​
Configure the index

Go to Infrastructure > Artifact repositories and add a Google Artifact Registry index, filling in the project ID, region, and repository name. Chalk uses these to construct the index URL (https://<region>-python.pkg.dev/<project>/<repo>/simple/) and mints a fresh OAuth access token at build time.

​
Preauthenticated

Use a Preauthenticated index when you have a fully formed authenticated index URL that you can hand to pip/uv as-is, such as a JFrog Artifactory or self-hosted devpi URL containing a username and access token.

​
Store the index URL as a secret

Store the complete URL (including any auth) as a secret in your team’s secret store. The URL should look like one of:

https://<user>:<token>@<host>/api/pypi/<repo>/simple/
https://<host>/api/pypi/<repo>/simple/    # if no auth is needed

​
Configure the index

Go to Infrastructure > Artifact repositories, add a Preauthenticated index, and set Index URL Secret to the locator or name of the secret you just created. Chalk reads the secret at build time and uses the value verbatim as the index URL.

​
Configure your Python environment

After you configure any of the indexes above, include your private packages in your pyproject.toml like any other dependency. Chalk’s builder will resolve them through the configured indexes during deployment.

​
Naming and other options

Each index gets an auto-derived name (the first label of the index URL’s hostname; e.g. https://pypi.org/simple → pypi). You can override this with the Name (override) field. If two indexes derive the same name, Chalk auto-suffixes with -2, -3, etc.

The Options tab exposes two global toggles that affect the rendered uv.toml:

  • Prefer private indexes: When enabled, the rendered [[index]] block for PyPI is marked default = true, so uv treats PyPI as the fallback and searches your private indexes first.
  • Unsafe first match: When enabled, the rendered uv.toml sets index-strategy = "unsafe-first-match".