Skip to content
Picket

Marketplaces

Picket is distributed through a GitHub Action and an Azure DevOps PicketScan@1 task. Both surfaces use the same scanner, report, cache, and security contracts as local execution.

The marketplace surfaces are:

  • GitHub Marketplace listing for the repository action,
  • Azure DevOps Marketplace extension for PicketScan@1.

Shared Requirements

Section titled “Shared Requirements”

Marketplace packages use the release provenance of the CLI artifacts:

  • semver release tags,
  • immutable patch tags,
  • mutable major tags that move only after validation,
  • SHA-256 checksums,
  • artifact attestations where the platform supports them,
  • generated input and output references,
  • sanitized screenshots and examples,
  • MIT license metadata,
  • clear privacy statements,
  • rollback instructions.

Examples, screenshots, summaries, and generated docs must not contain raw secrets. Redacted sample reports are acceptable when they exercise realistic paths, rule IDs, and counts.

GitHub Marketplace

Section titled “GitHub Marketplace”

The GitHub Action listing is driven by the root action.yml, release tags, README content, and marketplace metadata. The action keeps the same input names, output names, summary behavior, annotation behavior, SARIF upload path, cache behavior, fail modes, and redaction rules documented in docs/ACTION.md.

Release requirements:

  • keep action.yml as the source of truth for action inputs and outputs,
  • identify willibrandon as the action author and use supported shield/green Marketplace branding,
  • generate the docs reference from action.yml,
  • publish immutable vX.Y.Z tags for every release,
  • update the mutable vX tag only after CI, docs, action smoke, and release artifact validation pass,
  • document least-privilege permissions examples,
  • include a SARIF/code scanning example,
  • keep security-events: write required only when SARIF upload is enabled,
  • verify the action on pull request and push workflows before updating the marketplace listing.

The listing should describe the scanner in terms of local-first secrets scanning, Native AOT CLI distribution, Gitleaks compatibility, native validation, reports, baselines, cache, and privacy. It should not imply that live network validation runs by default.

GitHub’s supported Action publication flow requires a repository owner to edit the immutable release in the GitHub web interface, select Publish this Action to the GitHub Marketplace, choose categories, accept the GitHub Marketplace Developer Agreement when prompted, and complete two-factor authentication. Use Security as the primary category and Code quality as the secondary category. GitHub CLI and the public Releases REST API do not expose the Marketplace publication control.

Azure DevOps Marketplace

Section titled “Azure DevOps Marketplace”

The Azure DevOps Marketplace extension packages the PicketScan@1 task and the documentation needed for pipeline authors to use it safely.

The extension scaffold lives under azure-devops/: azure-devops/vss-extension.json declares the marketplace contribution and azure-devops/tasks/PicketScanV1/task.json declares the task inputs, outputs, and Node handler. Release automation packages the VSIX, applies the stable release version, writes a SHA-256 sidecar, and attests the artifact before the GitHub Release is created or updated.

The manifest declares the Marketplace icon and links to documentation, license, privacy, source, and support. The task folder contains the required 32-by-32 task icon. Packaged PRIVACY.md, COMPATIBILITY.md, and CHANGELOG.md files keep policy, agent requirements, and release history available with the VSIX.

Package contents:

  • VSIX manifest,
  • task metadata,
  • task icon,
  • README,
  • changelog,
  • MIT license,
  • privacy statement,
  • agent compatibility matrix,
  • input and output reference generated from task metadata,
  • release artifact acquisition or bundled binary metadata.

Release requirements:

  • keep task behavior as a thin wrapper around the CLI,
  • validate VSIX packaging before publish,
  • publish a stable task major line such as PicketScan@1,
  • evolve compatible task inputs additively,
  • use signed or checksummed CLI artifacts,
  • document PAT and job-token scope guidance,
  • document Azure DevOps Services and Azure DevOps Server support,
  • smoke test on Microsoft-hosted Windows, Linux, and macOS agents,
  • keep live Azure DevOps API tests opt-in.

Release Flow

Section titled “Release Flow”

Marketplace packaging happens while the scanner release artifacts are built and verified:

  1. Build and test the repository.
  2. Run docs generation and stale-doc checks.
  3. Publish Native AOT binary artifacts for supported RIDs.
  4. Package the Azure DevOps VSIX for stable release tags.
  5. Pack and publish the NuGet library and dotnet tool packages.
  6. Write per-asset checksums and aggregate checksums.
  7. Create artifact attestations where supported.
  8. Create or update the GitHub Release.
  9. Publish the Azure DevOps extension from the attested VSIX.
  10. Advance the GitHub Action major tag to the immutable release commit.
  11. Publish the immutable Action release through GitHub’s Marketplace release control.
  12. Verify that the Marketplace page exposes the exact immutable release tag.

Publication

Section titled “Publication”

Stable vMAJOR.MINOR.PATCH tags publish the Azure DevOps extension and advance the GitHub Action release channel through .github/workflows/release.yml. Prerelease tags package neither the Azure DevOps extension nor mutable GitHub Action tags.

The workflow first creates or updates the immutable GitHub Release. Azure DevOps publication waits for NuGet, container, Homebrew, Scoop, and WinGet release jobs, then downloads picket-<tag>-azure-devops.vsix and its checksum from that release. scripts/Validate-MarketplaceRelease.cs verifies the sidecar hash, canonical stable version, bounded archive structure, required assets, willibrandon.picket identity, PicketScan@1 metadata, and icon dimensions. The workflow verifies the GitHub artifact attestation before invoking the pinned tfx-cli. It does not use scope, validation, certificate, or wait bypasses.

Azure publication uses AZURE_DEVOPS_MARKETPLACE_PAT and the existing willibrandon.picket extension. The extension manifest carries the Marketplace Public gallery flag before packaging and attestation. A rerun queries the published extension and skips tfx extension publish when the release version already exists. After Azure publication succeeds, the workflow creates or moves only the mutable GitHub Action vMAJOR ref to the immutable release commit through the Git refs API.

The workflow cannot select GitHub’s Marketplace publication control because GitHub does not expose it through the public API. Its final Verify GitHub Marketplace listing job checks https://github.com/marketplace/actions/picket-secret-scanner for both willibrandon/picket and the exact immutable tag. The job fails with the release-edit URL until the owner completes GitHub’s publication step, and it can be rerun after the listing propagates.

Rollback

Section titled “Rollback”

Rollback must be documented before marketplace publication:

  • move the mutable GitHub Action major tag back to the last known-good patch release,
  • leave immutable patch tags unchanged,
  • remove or deprecate a bad Azure DevOps extension version when the marketplace allows it,
  • publish a patched Azure DevOps task version when removal is not possible,
  • update release notes with the affected versions and replacement version,
  • keep scanner report schemas and baseline formats backward compatible unless the release is explicitly marked breaking.

To roll back the GitHub Action major tag, resolve the last known-good immutable patch tag to its commit and update the vMAJOR ref through the Git refs API. Immutable patch tags remain unchanged. Azure DevOps Marketplace versions cannot be overwritten or downgraded; publish a higher patched extension version and deprecate the affected version through the Marketplace portal when available.

Required Secrets

Section titled “Required Secrets”

Repository secrets should be narrowly scoped:

Secret Purpose
NUGET_API_KEY Publish approved NuGet packages and tools.
AZURE_DEVOPS_MARKETPLACE_PAT Publish the Azure DevOps Marketplace VSIX package.
PICKET_GITHUB_SECRET_SCANNING_PAT Optional hosted-alert oracle capture for the Picket repository. GitHub Actions secret names cannot start with GITHUB_.
AZURE_DEVOPS_TEST_PAT Optional live Azure DevOps integration tests against a dedicated test organization.

AZURE_DEVOPS_TEST_PAT is consumed by the manual Live Azure DevOps workflow, not by default push or pull-request CI.

PICKET_GITHUB_SECRET_SCANNING_PAT is consumed by the manual Live GitHub Secret Scanning Oracle workflow, not by default push or pull-request CI.

GitHub Releases, GitHub Pages, artifact attestations, and GitHub Action tag updates use built-in GitHub workflow credentials.

Gates

Section titled “Gates”

Marketplace-related CI gates should cover:

  • stale generated docs,
  • action smoke tests,
  • exact-version GitHub Marketplace listing verification,
  • VSIX package validation,
  • metadata validation,
  • generated reference consistency,
  • no local checkout paths in docs or package metadata,
  • no raw secrets in examples, screenshots, summaries, reports, annotations, or fixtures,
  • checksum and attestation presence for published CLI artifacts.