Skip to content

Latest commit

 

History

History
174 lines (136 loc) · 7.91 KB

INSTALL.adoc

File metadata and controls

174 lines (136 loc) · 7.91 KB
Raw

Installation Guide for Git Provider Sync

Table of Contents

1. Introduction

This guide will help you install Git Provider Sync on your computer. We’ll explain each step in simple terms and include information about security features.

2. Downloading Git Provider Sync

  1. Go to the Releases page on GitHub.

  2. Look for the latest version.

  3. Download the file that matches your computer type (we’ll help you choose in the next section).

3. Installation Methods

3.1. For Linux Users

Choose the option that matches your Linux system:

  1. Using package managers (easier method):

    • For Ubuntu or Debian-like systems: Download the .deb file and install it with:

      sudo apt install ./path-to-downloaded-file.deb

    • For Fedora or Red Hat-like systems: Download the .rpm file and install it with:

      sudo dnf install ./path-to-downloaded-file.rpm

    • For Alpine Linux: Download the .apk file and install it with:

      apk add --allow-untrusted ./path-to-downloaded-file.apk

  2. Using pre-compiled binaries:

    • Download the .tar.gz file that ends with linux_amd64.tar.gz for most computers, or linux_arm64.tar.gz for some newer or smaller computers.

    • Extract the file and run the program from there.

3.2. For Mac Users

  • Download the file ending with darwin_amd64.tar.gz for older Macs, or darwin_arm64.tar.gz for newer Macs with M1 or M2 chips.

  • Extract the file and run the program from there.

3.3. For BSD Users

  • Choose the file that matches your BSD variant (DragonFly, Free, Net, or Open) and computer type (usually amd64 or arm64).

  • Download and extract the file, then run the program from there.

3.4. Windows Users

Git Provider Sync is not planned to be released for Windows. If you need to use it on a Windows computer, you can use the Windows Subsystem for Linux (WSL) and follow the Linux installation steps.

3.5. Using Docker or Podman

If you’re familiar with Docker or Podman, you can run Git Provider Sync without installing it directly:

podman run --rm -it \
  -v ${PWD}/gitprovidersync.yaml:/usr/bin/gitprovidersync.yaml \
  ghcr.io/itiquette/gitprovidersync:<version> sync \
  --config-file /usr/bin/gitprovidersync.yaml

3.6. Build it yourself

For those who prefer to build from source:

  • …​-src.tar.gz

  • Source code (zip) (automatically added to Release Assets by GitHub)

  • Source code (tar.gz) (automatically added to Release Assets by GitHub) Replace <version> with the version number you want to use.

4. Verifying Your Download

To make sure your download is safe and hasn’t been tampered with:

  1. Download the gitprovidersync_checksums_sha256.txt file.

  2. Use a checksum tool to verify that the file you downloaded matches the checksum in this file.

5. Advanced Build and Release Security Assurance

Note
 You don’t need to understand or read this part, it is intended for someone with a special interest in Security.

Git Provider Sync includes several security features to ensure the integrity and authenticity of your download.

  1. SBOM (Software Bill of Materials): Each release includes SBOM files in JSON format (e.g., gitprovidersync<version>_<arch>.sbom.json). These files list all the components and dependencies used in the software.

  2. Checksums and Signatures:

    • gitprovidersync_checksums_sha256.txt: Contains SHA256 checksums for all release files.

    • gitprovidersync_checksums_sha256.txt.pem: A public certificate for verifying the signature.

    • gitprovidersync_checksums_sha256.txt.sig: A signature file for Cosign verification.

  3. SLSA Level 3 Attestation:

    • multiple.intoto.jsonl: This file provides signed provenance for attestation, which helps verify the build process.

These features allow you to:

  • Check the integrity of your download

  • Confirm that the build is reproducible

  • Validate the software’s dependencies

5.1. Detailed Explanation

Git Provider Sync includes several features to ensure the integrity, authenticity, and transparency of your download. Let’s explore these in more detail:

5.1.1. SBOM (Software Bill of Materials)

What it is

An SBOM is like a detailed ingredient list for software. It lists all components, libraries, and dependencies used in Git Provider Sync.

File format

gitprovidersync<version>_<arch>.sbom.json

Why it’s important

  • Transparency: You can see exactly what’s in the software.

  • Security: Helps identify if any components have known vulnerabilities.

  • Compliance: Useful for organizations that need to track software components.

How to use it

You can review the SBOM using tools like SPDX or CycloneDX viewers. This is especially useful for security teams or curious users who want to know more about the software’s composition.

5.1.2. Checksums and Signatures

Checksums file

gitprovidersync_checksums_sha256.txt

  • Contains SHA256 checksums for all release files.

  • Use it to verify the integrity of your download.

Public certificate

gitprovidersync_checksums_sha256.txt.pem

  • Used to verify the signature of the checksums file.

Signature file

gitprovidersync_checksums_sha256.txt.sig

  • Used with Cosign for advanced verification.

Why they’re important

  • Integrity: Ensures your download hasn’t been tampered with.

  • Authenticity: Confirms the software comes from the legitimate source.

How to use them

  1. Calculate the SHA256 checksum of your downloaded file.

  2. Compare it with the corresponding checksum in the .txt file.

  3. For advanced users: Use Cosign to verify the signature, ensuring the checksums file itself is authentic.

5.1.3. SLSA (Supply-chain Levels for Software Artifacts) Level 3 Attestation

What it is

SLSA is a security framework to prevent tampering, improve integrity, and secure packages and infrastructure in your projects, businesses or enterprises.

File

multiple.intoto.jsonl

Why it’s important

  • Build Integrity: Ensures the software was built in a secure and controlled environment.

  • Tamper Protection: Makes it extremely difficult for attackers to insert malicious code during the build process.

  • Traceability: Provides a verifiable record of how, when, and where the software was built.

What Level 3 means

  • The build process is fully scripted/automated and hermetic.

  • The source is version controlled and checked for reviews.

  • The build generates provenance explaining how the artifact was created.

How to use it

  • Advanced users can use SLSA verification tools to check the provenance and ensure it meets Level 3 requirements.

  • This is particularly important for enterprise environments or security-conscious users.

5.1.4. Understanding the Security Build And Release Possibilities

While these security features might seem complex, they work together to provide several layers of protection:

  1. Transparency: The SBOM lets you see what’s in the software.

  2. Integrity: Checksums ensure your download matches the original file.

  3. Authenticity: Signatures prove the software comes from the legitimate source.

  4. Build Security: SLSA attestation confirms the software was built securely.

For most users, simply checking the checksum is a good start. For those with higher security requirements, utilizing all these features provides a comprehensive security approach.

5.2. Verifying Your Download

For a basic check:

  1. Download the gitprovidersync_checksums_sha256.txt file.

  2. Use a checksum tool to calculate the SHA256 hash of your downloaded Git Provider Sync file.

  3. Compare your calculated hash with the one in the checksums file. They should match exactly.

For advanced verification:

  1. Use Cosign to verify the signature of the checksums file.

  2. Use SLSA verification tools to check the build provenance.

  3. Review the SBOM to understand all components included in the software.

Remember, You don’t need to understand or use all these features.