Makes Documentation

Makes is an open-source, production-ready CI/CD framework powered by Nix. It is designed to build both CI/CD pipelines and application environments with a focus on security, speed, and portability.

Key features include:

• Secure: Uses cryptographically signed dependencies for apps and pipelines.
• Easy: Single-command installation and dozens of generic CI/CD builtins.
• Fast: Supports distributed and granular caching.
• Portable: Runs on Docker, VMs, and any Linux-based OS.
• Extensible: Can be extended to work with any technology.

Makes implements 'Least Common Mechanism' by ensuring that, in standard configurations, users do not share state. Each user has their own personal /nix/store and a personal installation of Nix.

Store contents are not shared between users unless a user explicitly configures a read+write binary cache and sets the required binary cache secret.

Makes adheres to the SLSA (Supply Chain Levels for Software Artifacts) v0.1 specification, currently achieving SLSA Level 2. This framework ensures the integrity of software artifacts by securing the build and release process, source code, and dependencies against tampering.

Core Infrastructure Mapping

• Source: Managed via Git (GitHub).
• Platform: GitHub Actions, Makes, and the Nix package manager.
• Build Service: GitHub Actions using GitHub-hosted runners.
• Build Mechanism: Nix derivations.
• Environment: An isolated sandbox using Chroot and private namespaces (PID, mount, network, IPC, UTS) to prevent interference from other processes.
• Steps: Defined via Nix and shell scripting, versioned as code within the source repository.

All code submitted to the Makes repository is licensed under the MIT license.

To signal agreement to the Developer Certificate of Origin (DCO), you must sign your commits by adding a Signed-off-by: Full Name <email> line at the end of your commit message.

The Makes CLI is a Python application that runs in user-space. It does not require elevated or root privileges for standard operations. The following permissions are used:

• Write access to ${HOME}: Uses existing user permissions.
• Temporary file/directory creation: Respects the ${TMPDIR} environment variable.
• Nix Installation: Requires a system with Nix installed.
• Kernel Namespaces (Optional): Some advanced features may require privileges to create Kernel namespaces.

When building containers, Makes assembles OCI-compliant images (TAR files per layer plus a JSON manifest) using information from the Nix Store, avoiding the need for privileged daemons like Docker.

Makes uses Calendar Versioning (CalVer) for its stable releases. The ecosystem consists of two main components that must be kept in sync:

1. The Framework: The core logic used for evaluation.
2. The CLI: The command-line interface (invoked via $ m).

Important: To ensure the ecosystem works correctly, you must use the same version for both the framework and the CLI (e.g., both should be 24.12).

Release Types

• Stable releases: These do not have the Pre-release label. They are frozen and will not be modified.
• Unstable releases: These have the Pre-release label. They contain the latest features but may include bugs or breaking changes.

To get started with Makes, follow these steps:

1. Create a makes.nix file in your project root. Define your jobs using the makeScript function.
2. Run the job using the m command from your project root, specifying the directory and the job path.

Example makes.nix configuration:

{ makeScript, ...}: {
  jobs = {
    "/helloWorld" = makeScript {
      name = "helloWorld";
      entrypoint = "echo 'Hello World!'";
    };
  };
}

To invoke the job:

m . /helloWorld

Makes follows a 'fail-safe defaults' approach regarding file ownership and artifact sharing:

File Ownership

Generated files are created inside user-owned folders by default, inheriting the user's existing directory security. Users can opt-out of this via environment variables.

Binary Caching and Artifact Sharing

By default, the contents of the /nix/store are never published to the internet. The default configuration uses a read-only binary cache (e.g., https://cache.nixos.org) and no write binary cache.

To share artifacts with other users to improve performance, you must explicitly configure a read+write binary cache and provide the corresponding access secret.

To view the documentation site on your local machine, use the m command pointing to the documentation directory. This allows you to preview the docs site on localhost.

m . /docs/dev