{"id":13902960,"url":"https://github.com/blue-build/cli","last_synced_at":"2026-01-16T17:45:52.596Z","repository":{"id":218387027,"uuid":"746292046","full_name":"blue-build/cli","owner":"blue-build","description":"BlueBuild's command line program that builds custom Fedora Atomic images based on your recipe.yml","archived":false,"fork":false,"pushed_at":"2025-05-08T12:30:55.000Z","size":2267,"stargazers_count":96,"open_issues_count":31,"forks_count":14,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-08T13:36:47.290Z","etag":null,"topics":["cli","cli-tool","fedora","fedora-silverblue","ublue","ublue-os"],"latest_commit_sha":null,"homepage":"https://blue-build.org/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blue-build.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-01-21T16:32:34.000Z","updated_at":"2025-05-04T15:19:26.000Z","dependencies_parsed_at":"2024-01-21T17:28:06.964Z","dependency_job_id":"70eebcd2-b048-42ab-9cd0-e7d214a3b24b","html_url":"https://github.com/blue-build/cli","commit_stats":{"total_commits":489,"total_committers":15,"mean_commits":32.6,"dds":0.1901840490797546,"last_synced_commit":"1671ea2143a008694dd34c6d16582c5aa892f621"},"previous_names":["blue-build/cli"],"tags_count":71,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blue-build%2Fcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blue-build%2Fcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blue-build%2Fcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blue-build%2Fcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blue-build","download_url":"https://codeload.github.com/blue-build/cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254485062,"owners_count":22078767,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cli-tool","fedora","fedora-silverblue","ublue","ublue-os"],"created_at":"2024-08-06T22:01:31.307Z","updated_at":"2025-12-30T01:06:57.034Z","avatar_url":"https://github.com/blue-build.png","language":"Rust","readme":"[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/blue-build/cli/badge)](https://scorecard.dev/viewer/?uri=github.com/blue-build/cli)\n\n\u003cdiv align=\"center\"\u003e\n  \u003ccenter\u003e\n    \u003cimg src=\"https://github.com/blue-build/.github/assets/60004820/337323ed-70e4-4025-8c73-e8fe0c183c7c\" alt=\"BlueBuild. A minimal logo with a blue-billed duck holding a golden wrench in its beak.\" style=\"max-height: 300px;\" /\u003e\n  \u003c/center\u003e\n\u003c/div\u003e\n\n# BlueBuild\n\nBlueBuild's command line program that builds Containerfiles and custom images based on your recipe.yml.\n\n## Requirements\n\nThe `bluebuild` tool takes advantage of newer build features. Specifically bind, cache, and tmpfs mounts on the `RUN` instructions. We support using the following tools and their versions:\n\n- Docker - v23 and above\n- Podman - v4 and above\n- Buildah - v1.29 and above\n\n## Installation\n\nEvery image created with `bluebuild` comes with the CLI installed. If you have not built and booted a `bluebuild` created image, you can follow these instructions to install it.\n\n### Cargo\n\nThis is the best way to install as it gives you the opportunity to build for your specific environment.\n\n```bash\ncargo install --locked blue-build\n```\n\n### Podman/Docker\n\nThis will install the binary on your system in `/usr/local/bin`.\n\n```bash\npodman run --pull always --rm ghcr.io/blue-build/cli:latest-installer | bash\n```\n\n```bash\ndocker run --pull always --rm ghcr.io/blue-build/cli:latest-installer | bash\n```\n\n### Github Install Script\n\n```bash\nbash \u003c(curl -s https://raw.githubusercontent.com/blue-build/cli/main/install.sh)\n```\n\n### Distrobox\n\nWe package an `alpine` image with all the tools needed to run `bluebuild`. You can use `distrobox` to run the application without needing to install it on your machine. You can clone this repo locally and run:\n\n```bash\ndistrobox assemble create\n```\n\nThis will export `bluebuild` to your local machine and allow you to build images and test out your recipes. For security reasons, we keep this as a rootless image which means you will not be able to use this method to locally rebase to an image. If you want that capability, you should install the CLI tool directly.\n\nRefer to the [distrobox documentation](https://distrobox.it/usage/distrobox-export/) for more information.\n\n### Nix Flake\n\nYou can install this CLI through the Nix flake on [Flakehub](https://flakehub.com/)\n\n#### Non-nixos\n\nYou can install BlueBuild to your global package environment on non-nixos systems by running\n\n```shell\n# you can replace \"*\" with a specific tag\nnix profile install https://flakehub.com/f/bluebuild/cli/*.tar.gz#bluebuild\n```\n\n#### NixOS\n\nIf you are using a dedicated flake to manage your dependencies, you can add BlueBuild as a flake input throught the [fh](https://github.com/DeterminateSystems/fh) cli (that can be installed through nixpkgs) and add `bluebuild` to it.\n```nix\n{pkgs,inputs,...}: {\n    ...\n    environment.SystemPackages = [\n        inputs.bluebuild.packages.${pkgs.system}.bluebuild # change bluebuild with the fh added input name\n    ];\n    ...\n}\n```\n\nIf you are not using a dedicated nix flake, you can add the BlueBuild flake as a variable inside your `/etc/nixos/*.nix` configuration, though this requires you to run `nixos-rebuild` with the `--impure` variable, it is not advisable to do so.\n\n```nix\n{pkgs,...}:\nlet\n    bluebuild = builtins.fetchTarball \"https://flakehub.com/f/bluebuild/cli/*.tar.gz\";\nin {\n    ...\n    environment.SystemPackages = [\n        bluebuild.packages.${pkgs.system}.bluebuild\n    ];\n    ...\n}\n```\n\nYou can also use `nix develop .#` in this repos directory to run a nix shell with development dependencies and some helful utilities for building BlueBuild!\n\n## How to use\n\n### Generating `Containerfile`\n\nOnce you have the CLI tool installed, you can run the following to pull in your recipe file to generate a `Containerfile`.\n\n```bash\nbluebuild generate -o \u003cCONTAINERFILE\u003e \u003cRECIPE_FILE\u003e\n```\n\nYou can then use this with `docker`, `podman`, or `buildah` to build and publish your image. Further options can be viewed by running `bluebuild template --help`\n\n### Building\n\nIf you don't care about the details of the template, you can run the `build` command.\n\n```bash\nbluebuild build ./recipes/recipe.yml\n```\n\nThis will template out the file and build with `docker`, `podman`, or `buildah`.\n\n### Completions\n\nThe `bluebuild completions` command generates shell completions, printed to stdout. These completions can be stored for integration in your shell environment. For example, on a system with [bash-completion](https://github.com/scop/bash-completion/) installed:\n\n```bash\n# user completions\n$ bluebuild completions bash \u003e ~/.local/share/bash-completion/completions/bluebuild\n# system-wide completions\n$ bluebuild completions bash | sudo tee /usr/share/bash-completion/completions/bluebuild\n```\n\nSubsequent invocations of `bluebuild` will respond to `\u003cTab\u003e` autocompletions:\n\n```bash\n$ bluebuild # press \u003cTab\u003e\n-v           -V           --help       template     bug-report\n-q           --verbose    --version    upgrade      completions\n-h           --quiet      build        rebase       help\n```\n\nCurrently, bluebuild completions are available for `bash`, `zsh`, `fish`, `powershell`, `nushell`, and `elvish` shell environments. Please follow your shell's documentation for completion scripts.\n\n#### Local Builds\n\n##### Switch\n\nWith the switch command, you can build and boot an image locally using an `oci-archive` tarball. The `switch` command can be run as a normal user and will only ask for `sudo` permissions when moving the archive into `/etc/bluebuild`.\n\n```bash\nbluebuild switch recipes/recipe.yml\n```\n\nYou can initiate an immediate restart by adding the `--reboot/-r` option.\n\n#### CI Builds\n\n##### GitHub\n\nYou can use our [GitHub Action](https://github.com/blue-build/github-action) by using the following `.github/workflows/build.yml`:\n\n```yaml\nname: bluebuild\non:\n  schedule:\n    - cron: \"00 17 * * *\" # build at 17:00 UTC every day\n                          # (20 minutes after last ublue images start building)\n  push:\n    paths-ignore: # don't rebuild if only documentation has changed\n      - \"**.md\"\n  pull_request:\n  workflow_dispatch: # allow manually triggering builds\njobs:\n  bluebuild:\n    name: Build Custom Image\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      packages: write\n      id-token: write\n    strategy:\n      fail-fast: false # stop GH from cancelling all matrix builds if one fails\n      matrix:\n        recipe:\n          # !! Add your recipes here\n          - recipe.yml\n    steps:\n       # the build is fully handled by the reusable github action\n      - name: Build Custom Image\n        uses: blue-build/github-action@v1\n        with:\n          recipe: ${{ matrix.recipe }}\n          cosign_private_key: ${{ secrets.SIGNING_SECRET }}\n          registry_token: ${{ github.token }}\n          pr_event_number: ${{ github.event.number }}\n ```\n\n##### Gitlab\n\nWe also support GitLab CI! Fun fact, this project started out as a way to build these images in GitLab. You will want to make use of GitLab's [Secure Files](https://docs.gitlab.com/ee/ci/secure_files/index.html) feature for using your cosign private key for signing. Here's an example of a `.gitlab-ci.yml`:\n\n```yaml\nworkflow:\n  rules:\n    - if: $CI_COMMIT_BRANCH \u0026\u0026 $CI_OPEN_MERGE_REQUESTS \u0026\u0026 $CI_PIPELINE_SOURCE == \"push\"\n      when: never\n    - if: \"$CI_COMMIT_TAG\"\n    - if: $CI_PIPELINE_SOURCE == \"merge_request_event\"\n    - if: \"$CI_COMMIT_BRANCH \u0026\u0026 $CI_OPEN_MERGE_REQUESTS\"\n      when: never\n    - if: \"$CI_COMMIT_BRANCH\"\n\nstages:\n  - build\n\nbuild-image:\n  stage: build\n  image:\n    name: ghcr.io/blue-build/cli\n    entrypoint: [\"\"]\n  services:\n    - docker:dind\n  parallel:\n    matrix:\n      - RECIPE:\n          # Add your recipe files here\n          - recipe.yml\n  variables:\n    # Setup a secure connection with docker-in-docker service\n    # https://docs.gitlab.com/ee/ci/docker/using_docker_build.html\n    DOCKER_HOST: tcp://docker:2376\n    DOCKER_TLS_CERTDIR: /certs\n    DOCKER_TLS_VERIFY: 1\n    DOCKER_CERT_PATH: $DOCKER_TLS_CERTDIR/client\n  before_script:\n    # Pulls secure files into the build\n    - curl --silent \"https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/download-secure-files/-/raw/main/installer\" | bash\n    - export COSIGN_PRIVATE_KEY=$(cat .secure_files/cosign.key)\n  script:\n    - sleep 5 # Wait a bit for the docker-in-docker service to start\n    - bluebuild build --push ./recipes/$RECIPE\n```\n","funding_links":[],"categories":["cli","Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblue-build%2Fcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblue-build%2Fcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblue-build%2Fcli/lists"}