gittuf

https://gittuf.dev/
Admin
gittuf is a platform-agnostic Git security system designed to protect Git repositories from...
Tokens:18,298
Snippets:231
Trust Score:7.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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 <your signing key>
                       --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 name>

```

--------------------------------

### 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 <your signing key>

```

```bash
gittuf policy init -k <your sigining key> --policy-name <delegated 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 <your signing key>
```

--------------------------------

### 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 <your signing key> --policy-name <policy file 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 <the user's signing key>

```

```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 <your GPG key's fingerprint>

```

--------------------------------

### 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 <your signing key>
                                       --initial-root-principal <the root principals of the controller repository>
                                       --location <the location of the controller repository>
                                       --name <the name of the controller repository>

```

--------------------------------

### 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 <your signing key>

```

--------------------------------

### 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 <your signing key>

```

--------------------------------

### 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 <tag name>

```

--------------------------------

### 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 <path to your SSH key>

```

--------------------------------

### 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 <your signing key> --root-key <the public key of the user to be added>

```

--------------------------------

### 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 <your signing key> --policy-ley <the public key of the user to be added>

```

--------------------------------

### 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 <remote> refs/gittuf/*
git fetch <remote> 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 <your signing key> --public-key <the public keys of the person>
```

--------------------------------

### 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 <your signing key>
                                    --initial-root-principal <the root principals of the network repository>
                                    --location <the location of the network repository>
                                    --name <the name of the network repository>

```

--------------------------------

### 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 <branch name>

```

```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 <your signing key>
                       --rule-name <name>
                       --rule-pattern <pattern>
                       --authorize <principals>
```

--------------------------------

### 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 <your signing key>
                            --type threshold
                            --threshold 1
                            --rule-pattern <rule pattern>

```

```bash
gittuf trust add-global-rule -k <your signing key>
                             --type block-force-pushes
                             --rule-pattern <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 <person identifier> --public-key <the public keys of the person>

```

--------------------------------

### 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 <branch name>

```

--------------------------------

### 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 <branch to merge from> <branch to merge into>

```

--------------------------------

### 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 <your signing key> --threshold <desired 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 <your signing key> --policy-key-ID <the administrator's public 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 <person identifier> --public-key <the public keys of the person>

```
Tokens:
Raw