Add rough guide for alpha #7
Conversation
| 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. | ||
|
|
There was a problem hiding this comment.
I'm thinking we may want to have some quick examples of verification here, as we don't link back to the design here. It might be better to add these to either another file (i.e. examples.md) or otherwise stay consistent so the doc doesn't become cluttered.
| Here are some examples on how to verify: | |
| `gittuf verify-ref -f main` to verify the `main` branch. | |
| `gittuf verify-commit HEAD` to verify the commit at `HEAD`. |
I also think it might be good to have something noting the case as shown in the demo (i.e. a branch protection rule is created as well as a file protection rule; the file is updated with an unauthorized signature but the RSL is updated with an authorized one - attempting to verify the main branch would raise an error). This might be better suited for another document though.
guide.md
Outdated
| 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`. |
There was a problem hiding this comment.
I'm thinking we can add some clarification here to indicate that RSL updates are done automatically if the policy is updated (as mentioned in the design doc)?
| created using `gittuf rsl annotate`. | |
| created using `gittuf rsl annotate`. Note that this is not required when you update the policy, | |
| as the RSL records changes to the policy namespace automatically. |
This also ties back in with the UX as right now gittuf requires a good deal of "hand-holding" (but that should be implied by gittuf still being in alpha).
guide.md
Outdated
| 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. |
There was a problem hiding this comment.
Should we add a little blurb on how policy rules should look like?
| declared constraint. | |
| declared constraint. Policies can protect files (by specifying `file:` in the rule pattern, | |
| such as `file:README.md`) as well as git refs (such as `git:refs/heads/main`). |
| 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. | ||
|
|
There was a problem hiding this comment.
Piggybacking off of the signing key viabiltiy item, it might be a good idea to add a section dubbed "prerequisites" here to signal to the user that any "write" operations with gittuf require a signing key. Maybe something like this?
| ## Prerequisites | |
| Before using gittuf, we suggest having a valid signing key specified in your git configuration (i.e. `git config --local user.signingkey`). Note that this is required for any gittuf operations that write changes to the repository. | |
|
Can you submit these as a PR to the alpha-guide branch here? I'll merge it into the feature branch and then merge this one to deploy. |
|
I think the guide hits all the major points a user needs to get started with gittuf. Of course, since we're still in alpha things will be volatile and some commands may require some head-scratching. In any case, LGTM as a quickstart. |
Signed-off-by: Aditya Sirish <[email protected]> Co-authored-by: Pat Zielinski <[email protected]>
adityasaky
force-pushed
the
alpha-guide
branch
from
c432849 to
9275537
Compare
cc @patzielinski
I think you were working on something similar, I wanted to get an initial version of this up. Feel free to add / fix etc!