Blocking releases for use in your organization

There may be circumstances where a package adheres to all of your catalog standards, but it still shouldn't be used by developers. This could be a framework that doesn't match your current infrastructure or other organizational preferences. With the Tidelift Subscription, you can manage the use of these packages by using the blocking releases.

Blocked releases can be managed directly from a package's page.

Blocking/unblocking a single release 

A single release can be blocked from the status drawer of a given release. This gives you more control when there has been no standard violated in your catalog. 

Blocking multiple releases

Releases that you would like to block can be selected and the option to block will appear in the upper right corner of the table. 

Managing all of your blocked items' statuses

Navigating to the blocked items page

Catalog > Packages > “Manage” dropdown in the top right > click “Blocked items”

Block items page capabilities

• View a paginated list of “blocked items.” A “blocked item” can be:
  • A singular release for a package: npm/mypackage version 1.2.3
  • All current and future releases for a package ("*" for the release to be blocked)
  • The list of blocked items includes a block “reason.” This field defaults to “Manual bulk block,” and is otherwise a comment that the user provides.
• Add a new blocked item:
  • For the version, you can choose:
    
    • All current and future releases (this will create one "*" blocked item to block the entire package, even as new releases may be made)
    • A range of releases (this will create multiple blocked items, one per release, and block only the releases in the inclusive range end and start). The range is not persistent; it is only used to identify currently-known releases to create per-release blocks for. That is, future releases that match the range will not be blocked.
    • A single release
  • If the “reason” field is left blank, it will be given the default reason, “Manual bulk block"

• Delete a selected group of Blocked Items from the list, using the checkboxes on the left hand side

• Search by package name
• Filter by platform

Blocked item external API

We’ve added three endpoints to the Tidelift external API for managing a catalog’s blocked items (the API documentation for these can be found here):

GET /v1/:org_name/catalogs/:catalog_name/blocked_tems

Responds with a list of all of a catalog’s blocked items. The results are paginated, and the endpoint accepts query parameters for page and per_page. If no page parameters are provided, the results will start on page 1 and display 20 results per page by default:

{
"current_page": 1,
"next_page": null,
"prev_page": null,
"total_pages": 1,
"total_count": 1,
"per_page": 20,
"results": [
    {
        "id": "ef404eb1-9f69-40b3-9652-d66aff15fac1",
        "platform": "npm",
        "name": "lodash",
        "version": "1.0.0",
        "reason": "Notes on why the item was added to the blocked list",
        "created_by": "Org User",
        "created_at": "2024-03-08T15:12:19.657Z"
    }
  ]
}

POST /v1/:org_name/catalogs/:catalog_name/blocked_tems

Add either all current and future releases of a package, a single release, or a range of releases to a catalog’s blocked item list. The following request body samples demonstrate the different combinations of parameters required in order to either outright block the entire package, a single release, a release range, and etc:

//To block all versions of a package, current and future

//Request
{
"platform": "npm",
"name": "lodash",
"reason": "The reason for blocking the package."
}
//Response
{
   "ids": [
     "5e93bd3f-c1ee-400d-8e9a-aa9b268b4b9b"
   ]
}

// To block a single release (version 3.0.0

// Request

{ 
"platform": "npm",
"name": "lodash",
"version_low": "3.0.0",
"version_high": "3.0.0",
"reason": "The reason for blocking the release."
}

// Response

{
"ids": [
  "8d8fe54d-acf5-454b-a995-3a93b8c12fd5"
]
}

// To block a range of releases (versions 4.0.0, 4.5.0. 5.0.0)

// Request
{
"platform": "npm",
"name": "lodash",
"version_low": "4.0.0",
"version_high": "5.0.0",
"reason": "The reason for blocking the releases."
}

// Response
{
"ids": [
  "21cd0d45-5070-4212-b63c-73295a2fe728",
  "575a3fac-d070-4cec-8736-e7ddc802447c",
  "e522cca2-dd0a-465b-b455-d4870e3543a6",
]
}

// Block all releases up until a specific version (version 1.0.0, 1.5.0, and 2.0.0)

//Request
{
"platform": "npm",
"name": "lodash",
"version_low": "0",
"version_high": "2.0.0",
"reason": "The reason for blocking the releases."
}

//Response
{
"ids": [
  "5a51047c-610e-4f3d-9fce-ffa4bfeefb8a",
  "7e5068c5-f6af-4f3d-b326-145d765b9f94",
  "eee35735-7c57-469c-b6a8-7a89be4ae980",
]
}

The response will include a list of ids, which are UUIDs unique to an item on the block list. An id from this list can be passed to the following DELETE endpoint to remove a package or release from the blocked list.

DELETE /v1/:org_name/catalogs/:catalog_name/blocked_tems/:id

Removes a release or package from the catalog’s blocked item list. Pass the UUID of the blocked item as a path parameter to specify which blocked item to remove. It will respond with the id of the removed blocked item:

{ 
"id": "ef404eb1-9f69-40b3-9652-d66aff15fac1"
}