Package release workflow
This page describes the workflows associated with operating Rugged in a basic
Package release mode, where there is no Monitor Worker in play. See
Package release workflow with Monitor Worker for details
of operating in a Monitor Worker mode.
See the Sequence Diagram below for a visual representation.
Operations
In this mode of operation, the Rugged Administrator is responsible for ensuring
a rugged add-targets command is run (automatically or as part of a manual
process) in order to sign and incorporate new targets into the TUF repository.
This contrasts with the Monitor Worker mode, in which
the Packaging Pipeline need only place new targets in a directory, to be picked
up by the Monitor Worker to perform the equivalent steps to running a rugged add-targets.
Part 1: Build and upload new packages
In this part of the workflow, the Packaging Pipeline builds new package
releases as normal, and uploads them somewhere to be available for Rugged.
This part is the second step in a typical packaging process, where the pipeline
generates metadata associated for use by the package manager and repository.
Part 3: Rugged add-targets
In the final part of this mode of operation, the Packaging Pipeline (or
manually by the Rugged Administrator) will execute a rugged add-targets
command specifying the new targets (packages + metadata).
The add-targets command first iterates over the new targets to be added, and
incorporates them into the targets.json metadata, including a new signature.
Next, the snapshot.json metadata is updated and re-signed to reflect the
change to the targets.
Finally, the timestamp.json metadata is updated and signed to complete the
updates to the TUF repository.
Sequence Diagram
The diagram below illustrates a generic package release workflow with Rugged TUF signing integrated.
Examples:
sequenceDiagram
participant PP as Packaging
Pipeline
participant FS as Shared
Filesystem(s)
participant TUF as Rugged
CLI
participant TARGETS as Targets
Worker
participant SNAPSHOT as Snapshot
Worker
participant TIMESTAMP as Timestamp
Worker
autonumber
activate PP
PP->>PP: Clone code
rect rgba(0, 255, 255, .1)
note over PP,FS: Part 1: Build and upload new packages
note left of FS: <PACKAGE>-<VERSION>.zip
PP->>PP: Build package
PP->>FS: Upload package
activate FS
end
rect rgba(0, 255, 0, .1)
note over PP,FS: Part 2: Generate package metadata
note left of FS: <PACKAGE>.json
PP->>PP: Generate package
metadata
PP->>FS: Upload package metadata
end
PP->>TUF: `rugged add-targets foo/foo.zip foo/package.json [...]`
activate TUF
rect rgba(0, 0, 255, .1)
note over PP,FS: Part 3: Rugged add-targets
note right of FS: TUF signing
TUF->>TARGETS: list of target files to sign
activate TARGETS
loop For each target file
FS-->>TARGETS: Read target file
TARGETS->>TARGETS: Update Targets metadata
(with signature of target file)
end
TARGETS->>TARGETS: Sign Targets metadata
TARGETS-->>FS: Write updated Targets metadata
note left of TUF: targets.json
TARGETS->>TUF: Return status message
deactivate TARGETS
TUF->>PP: Print status message
TUF->>SNAPSHOT: Trigger Snapshot update
activate SNAPSHOT
SNAPSHOT->>SNAPSHOT: Update and sign
Snapshot metadata
SNAPSHOT-->>FS: Write updated Snapshot metadata
note left of TUF: snapshot.json
SNAPSHOT->>TUF: Return status message
deactivate SNAPSHOT
TUF->>PP: Print status message
TUF->>TIMESTAMP: Trigger Timestamp update
activate TIMESTAMP
TIMESTAMP->>TIMESTAMP: Update and sign
Timestamp metadata
TIMESTAMP-->>FS: Write updated Timestamp metadata
deactivate FS
note left of TUF: timestamp.json
TIMESTAMP->>TUF: Return status message
deactivate TIMESTAMP
TUF->>PP: Print status message
end
deactivate TUF
deactivate PP