Create an artifact

Sign in with your FABRIC account, then choose Create Artifact on the Artifacts page. Creating artifacts requires a FABRIC account with JupyterHub access. Give it a title, a short and a long description, tags, and a visibility:

• Author - only the artifact's authors can see it.
• Project - authors and members of the chosen FABRIC project.
• Public - everyone, including people who are not signed in.

Clearing Show Authors or Show Project hides them from non-authors, for double-blind review. Authors can add co-authors by their FABRIC user UUID on the artifact's Edit page; every author can manage the artifact.

Versions

An artifact holds one or more versions. Each version is a single archive with a permanent URN, downloadable by anyone allowed to see the artifact.

• Upload - on the artifact page, use Add a new Version with a .tgz or .tar.gz file.
• Import from GitHub - copy the source of a release or tag from a linked repository (below), by hand or automatically.
• Disable / enable - a disabled version stays recorded but cannot be downloaded. Uploaded and GitHub versions can live side by side.

Link a GitHub repository

On the artifact page, an author enters owner/repo or https://github.com/owner/repo under Link a GitHub repository and chooses Link repository. Only public repositories on github.com can be linked, and each artifact links at most one.

Versions published this way are credited to the author who linked (or last re-confirmed) the repository. If that person stops being an author, the page shows Publishing paused until a current author chooses Re-confirm; the same applies if the repository is transferred or recreated. A plain rename is followed automatically. Unlink stops publishing and keeps every version already imported.

Import releases and tags by hand

Under GitHub releases and tags, choose Show releases and tags. The list shows published GitHub Releases first (with their name, date and any pre-release badge), then every git tag that has no Release, marked tag. Choose Import on a row to copy that version's source archive into FABRIC storage.

• A release import keeps the release's name, publication date and pre-release flag.
• A tag import records the tag, its commit and the commit date. Draft releases count as plain tags.
• Importing a tag that is already imported returns the existing version; nothing is duplicated.

Publish automatically with GitHub Actions

1. Link the repository to the artifact.
2. On the artifact page, expand Publish automatically with GitHub Actions and choose Copy workflow. That copy already contains this site's address and your artifact's UUID.
3. In the repository, save it as .github/workflows/publish-artifact.yml and commit it to the default branch.
4. Publish a GitHub Release, or push a tag (git tag v1.2.0 && git push origin v1.2.0). The workflow runs and the new version appears on the artifact page within a minute or two.

For reference, the workflow looks like this; the artifact page fills in the UUID for you:

name: Publish to FABRIC Artifact Manager
# Runs for a published release and for a pushed tag. When one action does both, the
# second run finds the version already imported and succeeds without a second copy.
on:
  release:
    types: [published]
  push:
    tags: ['*']
permissions:
  id-token: write
  contents: read
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Publish ${{ github.event.release.tag_name || github.ref_name }}
        env:
          AMGR_URL: "https://artifacts.fabric-testbed.net"
          ARTIFACT_UUID: "replace-with-your-artifact-uuid"
          TAG: ${{ github.event.release.tag_name || github.ref_name }}
        run: |
          set -euo pipefail
          OIDC_TOKEN=$(curl -sSf --get --data-urlencode "audience=$AMGR_URL" \
            -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL" | jq -r .value)
          curl -sS --fail-with-body --retry 5 --retry-delay 15 --retry-all-errors -X POST \
            "${AMGR_URL%/}/api/artifacts/$ARTIFACT_UUID/repo/publish" \
            -H "Authorization: Bearer $OIDC_TOKEN" -H 'Content-Type: application/json' \
            --data "$(jq -cn --arg tag "$TAG" '{tag: $tag}')"

Things worth knowing:

• It runs from the tagged commit. GitHub runs the workflow file as it exists in the commit being released or tagged, so tags made before the workflow was committed will not publish themselves; import those by hand.
• Releases and tags together. Creating a Release usually pushes its tag too, so two runs start. Whichever finishes first creates the version; the other finds it and succeeds without a duplicate. If the tag run wins, the version carries the tag's details rather than the release name.
• Pull requests never publish. Runs triggered by pull_request or pull_request_target are refused, so forks cannot publish to your artifact.
• Organization policies. If your GitHub organization restricts Actions, it must allow this workflow to run; no other repository or organization setting is needed.

Which token goes where

Scripting with the REST API

Everything on the artifact page can also be done through the API, documented interactively at /api/swagger/. Authenticate with your FABRIC token: in the FABRIC Portal, open Experiments › Manage Tokens, create a token and use its id_token value. Treat it like a password and never commit it to a repository.

export FABRIC_TOKEN='...'   # id_token from the FABRIC Portal

# List an artifact's GitHub releases and tags
curl -sS -H "Authorization: Bearer $FABRIC_TOKEN" \
  https://artifacts.fabric-testbed.net/api/artifacts/<artifact-uuid>/repo/releases

# Import one of them as a new version
curl -sS -X POST -H "Authorization: Bearer $FABRIC_TOKEN" -H 'Content-Type: application/json' \
  --data '{"tag": "v1.2.0"}' \
  https://artifacts.fabric-testbed.net/api/artifacts/<artifact-uuid>/repo/import

An import made this way is credited to you, and you must be an author of the artifact.

Troubleshooting GitHub publishing

When a publish run fails, open it in the repository's Actions tab: the last lines of the Publish step show the HTTP status and the Artifact Manager's message.

Limits

• Public repositories on github.com only; GitHub Enterprise is not supported.
• Source archives up to 75 MiB. Release assets (files attached to a Release) are not imported - only the repository source at that commit.
• 10 new GitHub versions per artifact per UTC day, shared by the web page, the API and Actions. Re-importing an existing tag does not count.
• The list shows up to 500 releases and up to 500 other tags; older ones can still be imported by name through the API.