Publish to Packages

A Buildkite plugin that publishes build artifacts and attestations to Buildkite Packages.

This plugin authenticates with Buildkite Packages using an Agent OIDC token, so your registry needs to be configured with a suitable OIDC policy.

Quick Start

Minimal

steps:
  - label: "Publish Gem"
    plugins:
      - publish-to-packages#v2.2.0:
          artifacts: "awesome-logger-*.gem"
          registry: "acme-corp/awesome-logger"

The Works

steps:
  - label: "Publish Gem"
    plugins:
      - publish-to-packages#v2.2.0:
          artifacts: "awesome-logger-*.gem"
          registry: "acme-corp/awesome-logger"
          attestations: # optional
            - "gem-build.attestation.json"
            - "gem-package.attestation.json"
          artifact_build_id: "${BUILDKITE_TRIGGERED_FROM_BUILD_ID}" # optional

Options

artifacts (string, required)

A glob pattern for artifacts to publish to Buildkite Packages from Build artifacts.

registry (string, required)

Buildkite Packages registry to publish to.

• Full format is <organization>/<registry_name> (e.g. acme-corp/awesome-logger).
• <organization> defaults to your Buildkite organization if omitted (e.g. awesome-logger).

attestations (string or array of strings, optional)

One or more attestations from artifact storage to publish along with each package created from artifacts.

Each attestation file must be a valid JSON object. You can use Generate Provenance Attestation plugin to generate a valid SLSA Provenance attestation in your Buildkite pipeline.

If artifact_build_id is specified, attestations will be downloaded from the relevant build artifact storage.

artifact_build_id (string, optional)

Configures the plugin to download artifacts from a different build, referenced by its UUID.

When this option is not specified, the plugin defaults to downloading artifacts from the build that it is running in.

This is typically used when package building and package publishing are split across two different pipelines and the former triggers the latter. See Building and publishing from different pipelines example below.

Usage

Building and publishing from the same pipeline

Build Gem step builds and uploads awesome-logger-*.gem package to the build artifact storage.

Publish Gem step uses Publish to Packages to publish the package from the build artifact storage to acme-corp/awesome-logger Packages registry.

Globbing (awesome-logger-*.gem) is a good way to accommodate version changes/increments (e.g. awesome-logger-1.0.5.gem).

steps:
  - label: "Build Gem"
    key: "build-gem"
    command: "gem build awesome-logger.gemspec"
    artifact_paths: "awesome-logger-*.gem" # upload to build artifact storage

  - label: "Publish Gem"
    depends_on: "build-gem"
    plugins:
      - publish-to-packages#v2.2.0:
          artifacts: "awesome-logger-*.gem" # publish from build artifact storage
          registry: "acme-corp/awesome-logger"

Building and publishing from different pipelines

There are two pipelines in this example:

1. Build Package pipeline
2. Publish Package pipeline

Build Package pipeline builds a gem, uploads it to its artifact storage and triggers the Publish Package pipeline to publish the package.

In Publish Packages pipeline, the artifact_build_id option is specified to reference the build that triggered it. This configures the plugin to download artifacts from the Build Package build that triggered it.

# build.pipeline.yml

steps:
  - label: "Build Gem"
    key: "build-gem"
    command: "gem build awesome-logger.gemspec"
    artifact_paths: "awesome-logger-*.gem" # upload to build artifact storage

  - label: "Trigger Publish pipeline"
    depends_on: "build-gem"
    trigger: "publish-package-pipeline"
    branches: "${BUILDKITE_BRANCH}"
    build:
      commit: "${BUILDKITE_COMMIT}"
      branch: "${BUILDKITE_BRANCH}"

# publish.pipeline.yml

steps:
  - label: "Publish Gem"
    plugins:
      - publish-to-packages#v2.2.0:
          artifacts: "awesome-logger-*.gem"
          registry: "acme-corp/awesome-logger"
          artifact_build_id: "${BUILDKITE_TRIGGERED_FROM_BUILD_ID}"

Building and publishing with a provenance attestation

steps:
  - label: "Build Gem"
    key: "build-gem"
    command: "gem build awesome-logger.gemspec"
    artifact_paths: "awesome-logger-*.gem" # upload to build artifact storage
    plugins:
      - generate-provenance-attestation#v1.0.0:
          artifacts: "awesome-logger-*.gem" # publish from build artifact storage
          attestation_name: "gem-build.attestation.json"

  - label: "Publish Gem"
    depends_on: "build-gem"
    plugins:
      - publish-to-packages#v2.2.0:
          artifacts: "awesome-logger-*.gem" # publish from build artifact storage
          registry: "acme-corp/awesome-logger"
          attestations: "gem-build.attestation.json"