diff --git a/guide.md b/guide.md index 63a8c7c..80a6c96 100644 --- a/guide.md +++ b/guide.md @@ -4,8 +4,56 @@ layout: default nav_order: 4 --- -Coming soon! - Many of gittuf's core features are under active development and, therefore, are -rapidly changing. A detailed user guide will be published here when gittuf -reaches beta. +rapidly changing. A more detailed user guide will be published here when gittuf +reaches beta. For now, this guide presents the workflow for using gittuf's alpha +releases. + +## Root of Trust + +First, it is necessary to establish the +[root of trust](https://github.com/gittuf/gittuf/blob/main/docs/design-document.md#managing-gittuf-root-of-trust) +for the gittuf policies. To do so, the repository's owners must use the `trust` +subcommand. The root of trust can be initialized using `gittuf trust init`, +presenting the command with the root key. + +After the root of trust itself is established, it must be updated to declare the +primary policy's keys. This is achieved using `gittuf trust add-policy-key`. A +companion `gittuf trust remove-policy-key` may be used to revoke a previously +trusted key for the primary policy. + +## gittuf Policies + +[The policies](https://github.com/gittuf/gittuf/blob/main/docs/design-document.md#managing-gittuf-policies) +themselves are managed using the `gittuf policy` subcommand. If a policy file +does not already exist, it must be first initialized using `gittuf policy init`. + +After a policy file is established, it may be updated with specific rules, +setting constraints on one or more namespaces. Specifically, `gittuf policy +add-rule` can be used to add a rule to the specified policy file, while its +companion `gittuf policy remove-rule` can be used to remove a previously +declared constraint. + +## Reference State Log + +gittuf implements an authenticated +[reference state log](https://github.com/gittuf/gittuf/blob/main/docs/design-document.md#reference-state-log-rsl) +that tracks changes to the different Git references (eg. branches, tags) in a +repository. Currently, when a change is made to some reference, it must be +recorded in the RSL using `gittuf rsl record`. An RSL annotation entry can be +created using `gittuf rsl annotate`. + +## Verification + +gittuf supports various types of verification workflows. First, gittuf allows +users to verify policy conformance for a Git reference. This can be invoked +using `gittuf verify-ref`. In addition, gittuf also provides equivalents to +Git's `verify-commit` and `verify-tag`. These gittuf equivalents use the trusted +keys in gittuf policies to verify commit and tag signatures. + +## Syncing gittuf Namespaces + +Currently, gittuf's custom namespaces must be synced separately. The RSL may be +synced using `gittuf rsl remote` which includes support for push and pull +operations. Similarly, the `gittuf trust remote` or `gittuf policy remote` +commands can be used to sync the policy namespace.