### Run gittuf setup Source: https://gittuf.dev/quickstart Initializes gittuf in the current Git repository. The setup utility is experimental and pending inclusion via PR #1193. Requires a Git repository and a signing key configured. ```shell gittuf setup ``` -------------------------------- ### Install gittuf on Linux with Go Source: https://gittuf.dev/quickstart Recommended for Linux as package managers often have outdated versions. Installs gittuf and git-remote-gittuf via Go. ```shell go install github.com/gittuf/gittuf@latest go install github.com/gittuf/gittuf/internal/git-remote-gittuf@latest ``` -------------------------------- ### Install gittuf on Windows with Winget Source: https://gittuf.dev/quickstart Uses the Windows package manager Winget to install gittuf and its git-remote-gittuf companion tool. ```shell winget install gittuf.gittuf winget install gittuf.git-remote-gittuf ``` -------------------------------- ### Install gittuf on macOS with Homebrew Source: https://gittuf.dev/quickstart Installs gittuf using Homebrew. Requires Homebrew to be pre-installed. ```shell brew install gittuf ``` -------------------------------- ### Retrieve gittuf metadata Source: https://gittuf.dev/quickstart/source After installation, use the sync command to fetch the repository's metadata. ```bash gittuf sync ``` -------------------------------- ### Invoke the gittuf TUI with optional signing key Source: https://gittuf.dev/documentation/maintainers/tui Run this command to start the gittuf TUI. The `-k` flag specifies your signing key, which is only required if you intend to make changes to gittuf metadata; it is not needed for viewing operations. ```bash gittuf policy tui [-k your signing key] ``` -------------------------------- ### Protect Main Branch with Threshold Source: https://gittuf.dev/documentation/maintainers/policy/rules Example command to protect the main branch requiring authorization from both Alice and Bob with a threshold of 2. ```bash gittuf policy add-rule -k --rule-name protect-main --rule-pattern git:refs/heads/main --authorize Alice --authorize Bob --threshold 2 ``` -------------------------------- ### File Protection Rule Pattern Source: https://gittuf.dev/documentation/maintainers/policy/rules Example of a file protection rule pattern targeting the README.md file. ```text file:README.md ``` -------------------------------- ### Verify a branch with gittuf verify-ref Source: https://gittuf.dev/documentation/consumers/verifying Verifies all changes on a branch starting from the first commit where a policy was defined. If nothing is printed, verification succeeded. Use the --verbose flag to see detailed output, which may be extensive. ```bash gittuf verify-ref ``` -------------------------------- ### Branch Protection Rule Pattern Source: https://gittuf.dev/documentation/maintainers/policy/rules Example of a branch protection rule pattern targeting the main branch. ```text git:refs/heads/main ``` -------------------------------- ### Uninstall gittuf with Homebrew Source: https://gittuf.dev/documentation/maintainers/uninstalling Uninstalls gittuf on macOS or Linux when installed via Homebrew. ```shell brew remove gittuf ``` -------------------------------- ### Uninstall gittuf with Winget Source: https://gittuf.dev/documentation/maintainers/uninstalling Uninstalls the gittuf binary and its git remote helper on Windows via Winget. Run both commands to remove the two installed packages. ```shell winget remove gittuf.gittuf winget remove gittuf.git-remote-gittuf ``` -------------------------------- ### Initialize gittuf policy (gittuf policy init) Source: https://gittuf.dev/documentation/maintainers/policy/operations Initializes the main gittuf policy with a signing key. The second command initializes a separate policy file for a delegated policy administrator using the --policy-name flag. Note the typo 'sigining' in the source. ```bash gittuf policy init -k ``` ```bash gittuf policy init -k --policy-name ``` -------------------------------- ### Build gittuf with tests Source: https://gittuf.dev/quickstart/source Run the make command to execute all tests and build the gittuf binary. ```bash make ``` -------------------------------- ### Initialize Primary Rule File Source: https://gittuf.dev/documentation/maintainers/policy/initialization Use this command to create the primary rule file in the repository directory. ```bash gittuf policy init -k ``` -------------------------------- ### Initialize Delegated Rule File Source: https://gittuf.dev/documentation/maintainers/policy/initialization Use this command to create a delegated rule file. The specified policy name must match the rule name that grants the delegation. ```bash gittuf policy init -k --policy-name ``` -------------------------------- ### Stage, sync, sign, and apply root metadata changes for threshold > 1 Source: https://gittuf.dev/documentation/maintainers/root/signing For multiple root of trust users with threshold greater than one, stage the changes, have other users sync and sign with gittuf trust sign -k, then apply the changes once all users have signed. Each user must sync after signing. ```bash gittuf trust stage origin ``` ```bash gittuf sync ``` ```bash gittuf trust sign -k ``` ```bash gittuf trust apply origin ``` -------------------------------- ### Enable gittuf cache with gittuf cache init Source: https://gittuf.dev/documentation/consumers/verifying Enables the verification cache in the current repository. After running this, successful verifications are cached locally, speeding up subsequent verifications. The cache is not uploaded to the remote and must be enabled on each machine. ```bash gittuf cache init ``` -------------------------------- ### Enable automatic push recording on existing clone Source: https://gittuf.dev/documentation/contributors/automatic For an already cloned repository, backs up the current remote URL to origin-backup and then sets the origin URL with the gittuf:: prefix. The backup is created in case issues arise with gittuf. ```bash git remote add origin-backup $(git remote get-url origin) git remote set-url origin gittuf::$(git remote get-url origin) ``` -------------------------------- ### Configure Git signing with GPG Source: https://gittuf.dev/documentation/contributors/signing-keys Configure Git to sign commits and tags with a GPG key. Replace the placeholder with your GPG key's fingerprint. Use --global instead of --local to apply to all repositories. ```bash git config --local commit.gpgsign true git config --local tag.gpgsign true git config --local user.signingkey ``` -------------------------------- ### Configure Git signing with Sigstore Source: https://gittuf.dev/documentation/contributors/signing-keys Configure Git to sign commits and tags with a Sigstore identity using gitsign. Set the gpg.format to x509 and specify gitsign as the program. Use --global instead of --local to apply to all repositories. ```bash git config --local commit.gpgsign true git config --local tag.gpgsign true git config --local gpg.format x509 git config --local gpg.x509.program gitsign ``` -------------------------------- ### Build gittuf without tests Source: https://gittuf.dev/quickstart/source Use the just-install target to build the gittuf binary without running the test suite. ```bash make just-install ``` -------------------------------- ### Declare a controller repository with gittuf trust add-controller-repository Source: https://gittuf.dev/documentation/maintainers/multirepo/network Run this command on the repository that will inherit a controller's global rule policy. It requires your signing key, the root principals of the controller repository, its location, and a name. After adding, stage the updated root of trust metadata, obtain required signatures, and apply the metadata. ```bash gittuf trust add-controller-repository -k --initial-root-principal --location --name ``` -------------------------------- ### Enable controller repository with gittuf trust make-controller Source: https://gittuf.dev/documentation/maintainers/multirepo/controller Enables controller functionality on a gittuf repository. Run this command on the repository you want to enable, then stage the updated root of trust metadata, obtain required signatures, and apply the metadata. After this, other repositories can inherit the global rule policy declared by the controller. ```bash gittuf trust make-controller -k ``` -------------------------------- ### Clone repository with gittuf:: prefix Source: https://gittuf.dev/documentation/contributors/automatic Clones a repository with automatic push recording enabled by adding the gittuf:: prefix to the clone URL. ```bash git clone gittuf::git@github.com:owner/repo ``` -------------------------------- ### Initialize root of trust with gittuf trust init Source: https://gittuf.dev/documentation/maintainers/root/initialization Initializes the root of trust for a gittuf repository. Must be run from the repository directory before any other gittuf operation. Creates the refs/gittuf/policy-staging reference with a commit containing the initialized root metadata. ```bash gittuf trust init -k ``` -------------------------------- ### Verify a tag with gittuf verify-ref Source: https://gittuf.dev/documentation/consumers/verifying Verifies a tag using the same command as for branches. Run this for each tag you want to verify. ```bash gittuf verify-ref ``` -------------------------------- ### Configure Git signing with SSH Source: https://gittuf.dev/documentation/contributors/signing-keys Configure Git to sign commits and tags with an SSH key. Set the gpg.format to ssh and provide the path to your SSH key. Use --global instead of --local to apply to all repositories. ```bash git config --local commit.gpgsign true git config --local tag.gpgsign true git config --local gpg.format ssh git config --local user.signingkey ``` -------------------------------- ### Stage and apply root metadata changes for threshold of one Source: https://gittuf.dev/documentation/maintainers/root/signing For a single root of trust user or threshold of one, stage the changes with gittuf trust stage, optionally using --local-only to avoid pushing to the remote, then apply them with gittuf trust apply. The apply command uses the same --local-only semantics as stage. ```bash gittuf trust stage origin ``` ```bash gittuf trust stage --local-only ``` ```bash gittuf trust apply origin ``` -------------------------------- ### Add Root of Trust User (gittuf trust add-root-key) Source: https://gittuf.dev/documentation/maintainers/root/users Adds a new user to the root of trust metadata. Requires the signing key and the public key file of the user to be added. Run this command for each user to be added. ```bash gittuf trust add-root-key -k --root-key ``` -------------------------------- ### Clone the gittuf repository Source: https://gittuf.dev/quickstart/source Use git to download the official gittuf source code from GitHub. ```bash git clone git@github.com:gittuf/gittuf cd gittuf ``` -------------------------------- ### Add gittuf:: prefix to remote URL Source: https://gittuf.dev/documentation/contributors/automatic Shows the original remote URL and the same URL with the gittuf:: prefix added to enable automatic push recording. The prefix is prepended to the beginning of the URL. ```text https://github.com/user/repository.git ``` ```text gittuf::https://github.com/user/repository.git ``` -------------------------------- ### Add Policy Administrator (gittuf trust add-policy-key) Source: https://gittuf.dev/documentation/maintainers/root/users Appoints a user as a policy administrator. Requires the signing key and the public key of the user to be added. Note: root users are not automatically policy administrators; this must be explicitly opted into. ```bash gittuf trust add-policy-key -k --policy-ley ``` -------------------------------- ### Verify network repositories with gittuf verify-network Source: https://gittuf.dev/documentation/maintainers/multirepo/controller Verifies that network repositories have properly inherited the controller's global rules. Requires pull access to all network repositories. gittuf clones all network repositories, verifies their metadata and that they declare the controller properly, then verifies all commits adhere to the global rules. On failure, an error message is output to the console. ```bash gittuf verify-network ``` -------------------------------- ### Sync gittuf references with git push and fetch Source: https://gittuf.dev/documentation/contributors/manual Alternative to `gittuf sync` for synchronizing gittuf's references using Git itself. Push and fetch gittuf's references under refs/gittuf/* to and from the remote. ```bash git push refs/gittuf/* git fetch refs/gittuf/*:refs/gittuf/* ``` -------------------------------- ### Add a person with gittuf policy add-person Source: https://gittuf.dev/documentation/maintainers/policy/users Adds a person as a principal to gittuf policy. Use the --policy-name flag to specify a non-primary policy. Repeat for each person you want to reference. ```bash gittuf person add-person -k --public-key ``` -------------------------------- ### Add network repository with gittuf trust add-network-repository Source: https://gittuf.dev/documentation/maintainers/multirepo/controller Adds a network repository to a controller repository. You must supply the initial root principals, the location (usually a URL), and a name for the repository. After adding network repositories, stage the updated root of trust metadata, obtain signatures, and apply the metadata. ```bash gittuf trust add-network-repository -k --initial-root-principal --location --name ``` -------------------------------- ### Record RSL and sync for non-gittuf user changes Source: https://gittuf.dev/documentation/contributors/no-gittuf Run after a non-gittuf user pushes changes. The first command records the RSL for each branch the user changed; the second pushes the generated metadata to the remote. ```bash gittuf rsl record ``` ```bash gittuf sync ``` -------------------------------- ### Add Rule Command Syntax Source: https://gittuf.dev/documentation/maintainers/policy/rules The command structure for adding a new rule to the gittuf policy. ```bash gittuf policy add-rule -k --rule-name --rule-pattern --authorize ``` -------------------------------- ### Add global rules with gittuf trust add-global-rule Source: https://gittuf.dev/documentation/maintainers/root/global-rules Use these commands to add global rules to the root of trust metadata. The first adds a minimum threshold rule requiring a specified number of signatures; the second adds a rule that blocks force-pushes. Both require a rule pattern: threshold rules accept 'git:' or 'file:', while block force-pushes rules only accept 'git:'. ```bash gittuf trust add-global-rule -k --type threshold --threshold 1 --rule-pattern ``` ```bash gittuf trust add-global-rule -k --type block-force-pushes --rule-pattern ``` -------------------------------- ### Add a person to gittuf policy (gittuf policy add-person) Source: https://gittuf.dev/documentation/maintainers/policy/operations Adds a person to the gittuf policy using their person ID and public keys. ```bash gittuf policy add-person --person-ID --public-key ``` -------------------------------- ### Verify the main branch Source: https://gittuf.dev/quickstart/source Run the verify-ref command to ensure the main branch adheres to the gittuf policy. It only outputs information if a verification error occurs. ```bash gittuf verify-ref main ``` -------------------------------- ### Record branch changes with gittuf rsl record Source: https://gittuf.dev/documentation/contributors/manual Run this command for each branch you changed before pushing to record the changes in gittuf's reference state log. gittuf signs the entry with your signing key and records it in the repository. You can also run it right before pushing after each commit, as long as all changes are recorded. ```bash gittuf rsl record ``` -------------------------------- ### List defined principals (gittuf policy list-principals) Source: https://gittuf.dev/documentation/maintainers/policy/operations Lists all persons currently defined in gittuf metadata. ```bash gittuf policy list-principals ``` -------------------------------- ### Sync gittuf metadata with gittuf sync Source: https://gittuf.dev/documentation/contributors/manual Use this command to synchronize gittuf's metadata with the remote server when you are ready to push your changes. It ensures gittuf's metadata is pushed along with your commits. ```bash gittuf sync ``` -------------------------------- ### Approve changes with gittuf attest authorize Source: https://gittuf.dev/documentation/contributors/approving-changes Run this command to approve changes from a source branch into a target branch. The user must have pulled down the changes first. gittuf records the approval as an attestation and uploads it to the remote server. ```bash gittuf attest authorize --from-ref ``` -------------------------------- ### List defined principals with gittuf policy list-principals Source: https://gittuf.dev/documentation/maintainers/policy/users Lists all persons currently defined in gittuf metadata. ```bash gittuf policy list-principals ``` -------------------------------- ### Update Policy Threshold (gittuf trust update-policy-threshold) Source: https://gittuf.dev/documentation/maintainers/root/users Sets the threshold of policy administrators required to agree on changes to the gittuf policy. Requires the signing key and the desired threshold value. ```bash gittuf trust update-policy-threshold -k --threshold ``` -------------------------------- ### Remove Policy Administrator (gittuf trust remove-policy-key) Source: https://gittuf.dev/documentation/maintainers/root/users Removes a policy administrator. Requires the signing key and the administrator's public key ID. ```bash gittuf trust remove-policy-key -k --policy-key-ID ``` -------------------------------- ### Update a person in gittuf policy (gittuf policy update-person) Source: https://gittuf.dev/documentation/maintainers/policy/operations Updates a person currently defined in gittuf policy. The details specified replace the current data, so all existing signing keys that should remain associated must be included. ```bash gittuf policy update-person --person-ID --public-key ``` -------------------------------- ### Update Root Threshold (gittuf trust update-root-threshold) Source: https://gittuf.dev/documentation/maintainers/root/users Adjusts the threshold of users required to sign changes to the root of trust metadata. Requires the signing key and the desired threshold value. ```bash gittuf trust update-root-threshold -k --threshold ``` -------------------------------- ### Merge approved changes with git checkout and git merge Source: https://gittuf.dev/documentation/contributors/approving-changes Use these commands to merge the approved changes from the feature branch into main. Run them after the required approvals have been added and synced. The merge commit will verify successfully. ```bash git checkout main git merge feature ``` -------------------------------- ### Update a person with gittuf policy update-person Source: https://gittuf.dev/documentation/maintainers/policy/users Updates a person's details in gittuf policy. The specified details replace the current data, so include all existing signing keys you wish to keep. ```bash gittuf policy update-person --person-ID --public-key ``` -------------------------------- ### Remove Root of Trust User (gittuf trust remove-key) Source: https://gittuf.dev/documentation/maintainers/root/users Removes a user from the root of trust metadata. Requires the signing key and the ID of the public key of the user to be removed. ```bash gittuf trust remove-key -k --root-key-ID ``` -------------------------------- ### Disable automatic push recording Source: https://gittuf.dev/documentation/contributors/automatic Disables automatic push recording by removing the gittuf:: prefix from the remote URL, restoring the original URL from the backup. ```bash git remote set-url origin $(git remote get-url origin-backup) ``` -------------------------------- ### Reset gittuf metadata with git update-ref Source: https://gittuf.dev/documentation/maintainers/uninstalling Deletes the four git references that store gittuf metadata. Run before reinitializing gittuf's root of trust. Users who have already pulled down gittuf metadata must also follow this procedure to prevent silent takeovers. ```shell git update-ref -d refs/gittuf/reference-state-log git update-ref -d refs/gittuf/policy-staging git update-ref -d refs/gittuf/policy git update-ref -d refs/gittuf/attestations ``` -------------------------------- ### Remove a person from gittuf policy (gittuf policy remove-person) Source: https://gittuf.dev/documentation/maintainers/policy/operations Removes a person from gittuf policy using their person ID. The person must not be referenced by any rule in the policy, otherwise gittuf raises an error. ```bash gittuf policy remove-person --person-ID ``` -------------------------------- ### Disable gittuf cache with gittuf cache delete Source: https://gittuf.dev/documentation/consumers/verifying Disables the verification cache and erases it, reverting to the default behavior. To re-enable, run gittuf cache init again. ```bash gittuf cache delete ``` -------------------------------- ### Cite gittuf paper (NDSS 2025) in BibTeX Source: https://gittuf.dev/ Use this BibTeX entry to cite the gittuf paper in academic publications. It includes the full author list, title, conference details, and DOI-like URL for the NDSS 2025 paper. ```bibtex @inproceedings{yelgundhalli2025, author = {Aditya Siria A Yelgundhalli and Patrick Zielinski and Reza Curtmola and Justin Cappos}, title = {{Rethinking Trust in Forge-Based Git Security}}, booktitle = {{32nd Network and Distributed System Security Symposium (NDSS 2025)}}, year = {2025}, isbn = {979-8-9894372-8-3}, address = {San Diego, CA}, url = {https://www.ndss-symposium.org/ndss-paper/rethinking-trust-in-forge-based-git-security/}, publisher = {{Internet Society}}, } ``` -------------------------------- ### Remove a person with gittuf policy remove-person Source: https://gittuf.dev/documentation/maintainers/policy/users Removes a person from gittuf policy by their person ID. The person must not be referenced by any rule, otherwise gittuf raises an error. ```bash gittuf policy remove-person --person-ID ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.