From 09491fe6d946f5e4d38a97aff6b7921fc5b564a8 Mon Sep 17 00:00:00 2001 From: Daniel Salazar Date: Wed, 8 Mar 2023 17:33:56 -0500 Subject: [PATCH] feat(doc): #940 move sections - Move several sections to new docs page - Other minor changes Signed-off-by: Daniel Salazar --- docs/mkdocs.yaml | 19 ++- docs/src/README.md | 3 - .../README.md => architecture.md} | 0 docs/src/configuring-ci-cd.md | 131 ++++++++++++++++++ .../README.md => contributing.md} | 0 .../{governance/README.md => governance.md} | 0 docs/src/index.md | 49 +++++++ .../{assurance/README.md => assurance.md} | 0 .../README.md => design-principles.md} | 0 .../security/{README.md => introduction.md} | 2 +- docs/src/security/{slsa/README.md => slsa.md} | 0 .../README.md => threat-model.md} | 0 docs/src/versioning.md | 51 +++++++ 13 files changed, 250 insertions(+), 5 deletions(-) delete mode 100644 docs/src/README.md rename docs/src/{architecture/README.md => architecture.md} (100%) create mode 100644 docs/src/configuring-ci-cd.md rename docs/src/{contributing/README.md => contributing.md} (100%) rename docs/src/{governance/README.md => governance.md} (100%) create mode 100644 docs/src/index.md rename docs/src/security/{assurance/README.md => assurance.md} (100%) rename docs/src/security/{design-principles/README.md => design-principles.md} (100%) rename docs/src/security/{README.md => introduction.md} (94%) rename docs/src/security/{slsa/README.md => slsa.md} (100%) rename docs/src/security/{threat-model/README.md => threat-model.md} (100%) create mode 100644 docs/src/versioning.md diff --git a/docs/mkdocs.yaml b/docs/mkdocs.yaml index 73168094..26aa48af 100644 --- a/docs/mkdocs.yaml +++ b/docs/mkdocs.yaml @@ -1,4 +1,4 @@ -site_name: Makes Documentation +site_name: 🦄 Makes site_url: https://fluidattacks.github.io/makes/ site_description: Documentation for Makes site_author: Fluid Attacks @@ -6,10 +6,27 @@ repo_url: https://github.com/fluidattacks/makes repo_name: Makes copyright: Copyright © 2023 Fluid Attacks, We hack your software. All rights reserved. +nav: + - index.md + - configuring-ci-cd.md + - versioning.md + - architecture.md + - contributing.md + - governance.md + - Security: + - security/introduction.md + - security/assurance.md + - security/design-principles.md + - security/slsa.md + - security/threat-model.md + strict: true docs_dir: src theme: name: material + features: + - content.code.copy + - navigation.instant markdown_extensions: - pymdownx.superfences: custom_fences: diff --git a/docs/src/README.md b/docs/src/README.md deleted file mode 100644 index b6c9a6a9..00000000 --- a/docs/src/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# 🦄 Makes - -A software supply chain framework powered by Nix. diff --git a/docs/src/architecture/README.md b/docs/src/architecture.md similarity index 100% rename from docs/src/architecture/README.md rename to docs/src/architecture.md diff --git a/docs/src/configuring-ci-cd.md b/docs/src/configuring-ci-cd.md new file mode 100644 index 00000000..5c10061c --- /dev/null +++ b/docs/src/configuring-ci-cd.md @@ -0,0 +1,131 @@ +# Configuring CI/CD + +A Makes container can be found +in the [container registry](https://github.com/fluidattacks/makes/pkgs/container/makes). + +You can use it +to run Makes on any CI/CD provider +that supports containers. + +Below you will find examples +for running makes +on some of the most popular +CI/CD providers. + +## Configuring on GitHub Actions + +[GitHub Actions](https://github.com/features/actions) +is configured through +[workflow files](https://docs.github.com/en/actions/reference/) +located in a `.github/workflows` directory in the root of the project. + +The smallest possible workflow file +looks like this: + +```yaml +# .github/workflows/dev.yml +name: Makes CI +on: [push, pull_request] +jobs: + helloWorld: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b + - uses: docker://ghcr.io/fluidattacks/makes:23.04 + # You can use any name you like here + name: helloWorld + # You can pass secrets (if required) as environment variables like this: + env: + SECRET_NAME: ${{ secrets.SECRET_IN_YOUR_GITHUB }} + with: + args: m . /helloWorld 1 2 3 + + # Add more jobs here, you can copy paste jobs.helloWorld and modify the `args` +``` + +## Configuring on GitLab CI/CD + +[GitLab CI/CD](https://docs.gitlab.com/ee/ci/) +is configured through a +[.gitlab-ci.yml](https://docs.gitlab.com/ee/ci/yaml/) file +located in the root of the project. + +The smallest possible .gitlab-ci.yml +looks like this: + +```yaml +# /path/to/my/project/.gitlab-ci.yml +/helloWorld: + image: ghcr.io/fluidattacks/makes:23.04 + script: + - m . /helloWorld 1 2 3 +# Add more jobs here, you can copy paste /helloWorld and modify the `script` +``` + +Secrets can be propagated to Makes +through [GitLab Variables](https://docs.gitlab.com/ee/ci/variables/), +which are passed automatically to the running container +as environment variables. + +## Configuring on Travis CI + +[Travis CI](https://travis-ci.org/) +is configured through a [.travis.yml](https://config.travis-ci.com/) file +located in the root of the project. + +The smallest possible .travis.yml +looks like this: + +```yaml +# /path/to/my/project/.travis.yml +os: linux +language: nix +nix: 2.3.12 +install: nix-env -if https://github.com/fluidattacks/makes/archive/23.04.tar.gz +env: + global: + # Encrypted environment variable + secure: cipher-text-goes-here... + # Publicly visible environment variable + NAME: value +jobs: + include: + - script: m . /helloWorld 1 2 3 + # You can add more jobs like this: + # - script: m . /formatBash +``` + +Secrets can be propagated to Makes through +[Travis Environment Variables](https://docs.travis-ci.com/user/environment-variables), +which are passed automatically to the running container +as environment variables. +We highly recommend you to use encrypted environment variables. + +## Configuring the cache + +If your CI/CD will run on different machines +then it's a good idea +to setup a distributed cache system +using [Cachix](https://cachix.org/). + +In order to do this: + +1. Create or sign-up to your Cachix account. +1. Create a new cache with: + - Write access: `API token`. + - Read access: `Public` or `Private`. +1. Configure `makes.nix` as explained in the following sections + +### Configuring trusted-users + +If you decided to go +with a Multi-user installation +when installing Nix, +you will have to take additional steps +in order to make the cache work. + +As the Multi-user installation +does not trust your user by default, +you will have to add yourself +to the `trusted-users` in the +[Nix Configuration File](https://www.mankier.com/5/nix.conf). diff --git a/docs/src/contributing/README.md b/docs/src/contributing.md similarity index 100% rename from docs/src/contributing/README.md rename to docs/src/contributing.md diff --git a/docs/src/governance/README.md b/docs/src/governance.md similarity index 100% rename from docs/src/governance/README.md rename to docs/src/governance.md diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 00000000..f2ad1815 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,49 @@ +# Getting started + +## Installation + +1. [Install Nix](https://nixos.org/download). + > **Note** + > We recommend getting the Single-user installation + > if you're new to Nix. +1. Install Makes: + + ```bash + $ nix-env -if https://github.com/fluidattacks/makes/archive/23.04.tar.gz + ``` + +## Usage + +The Makes command has the following syntax: + +```bash +$ m +``` + +where: + +- `` is a GitHub, GitLab or local repository. +- `` is a Makes job + that exists within the referenced repository. + If no job is specified, + Makes displays all available jobs. + +You can try: + +- `$ m github:fluidattacks/makes@main` +- `$ m github:fluidattacks/makes@main /helloWorld` +- `$ m gitlab:fluidattacks/makes-example-2@main` +- `$ m /path/to/local/repo` + +Makes is powered by [Nix](https://nixos.org). +This means that it is able to run +on any of the +[Nix's supported platforms](https://nixos.org/manual/nix/unstable/installation/supported-platforms.html). + +We have **thoroughly** tested it in +x86_64 hardware architectures +running Linux and MacOS (darwin) machines. + +## Want to get your hands dirty? + +Jump right into our [hands-on example](https://github.com/fluidattacks/makes-example)! diff --git a/docs/src/security/assurance/README.md b/docs/src/security/assurance.md similarity index 100% rename from docs/src/security/assurance/README.md rename to docs/src/security/assurance.md diff --git a/docs/src/security/design-principles/README.md b/docs/src/security/design-principles.md similarity index 100% rename from docs/src/security/design-principles/README.md rename to docs/src/security/design-principles.md diff --git a/docs/src/security/README.md b/docs/src/security/introduction.md similarity index 94% rename from docs/src/security/README.md rename to docs/src/security/introduction.md index 2e1c8a09..4bd5ad50 100644 --- a/docs/src/security/README.md +++ b/docs/src/security/introduction.md @@ -1,4 +1,4 @@ -# Security +# Introduction This section evaluates Makes using various standards and tries to address the security of Makes as an ecosystem diff --git a/docs/src/security/slsa/README.md b/docs/src/security/slsa.md similarity index 100% rename from docs/src/security/slsa/README.md rename to docs/src/security/slsa.md diff --git a/docs/src/security/threat-model/README.md b/docs/src/security/threat-model.md similarity index 100% rename from docs/src/security/threat-model/README.md rename to docs/src/security/threat-model.md diff --git a/docs/src/versioning.md b/docs/src/versioning.md new file mode 100644 index 00000000..92f5ed8d --- /dev/null +++ b/docs/src/versioning.md @@ -0,0 +1,51 @@ +# Versioning scheme + +We use [calendar versioning](https://calver.org/) for stable releases. + +Versioning is the same for both GitHub tags and Containers. + +You can find +the full list of versions in the +[GitHub releases page](https://github.com/fluidattacks/makes/releases). + +The Makes ecosystem has two components: +the framework itself, and the CLI (a.k.a. `$ m`). + +## Stable releases + +Stable releases are the ones that **do not have** the `Pre-release` label. +they are frozen. +We don't touch them under any circumstances. + +## Unstable releases + +Unstable releases are the ones +that **do have** the `Pre-release` label. +These releases have the latest Makes features +but can also come with breaking changes or bugs. + +## Versioning scheme for the framework + +You can ensure +that your project is always evaluated +with the same version of Makes +by creating a `makes.lock.nix` in the root of your project, +for instance: + +```nix +# /path/to/my/project/makes.lock.nix +{ + makesSrc = builtins.fetchGit { + url = "https://github.com/fluidattacks/makes"; + ref = "refs/tags/23.04"; + rev = ""; # Add a commit here + }; +} +``` + +## Compatibility information + +For the whole ecosystem to work +you need to use the **same version** +of the framework and the CLI. +For example: `23.04`.