Running Flox in CI/CD

Continuous integration (CI) and Continuous delivery (CD) is essential in today’s software development cycle. With Flox the exact same set of software can be used for local development and a CI/CD pipeline. This feature works out of the box with Flox because Flox environments work cross-platform and reproducibly by default. This means that you can spend less time debugging your CI/CD pipeline and more time developing your software. Let’s look at how you can use Flox with a variety of CI/CD platforms. For the following examples assume that you have a repository that contains a Flox environment, and assume that you’ve installed some Node.js dependencies for your project.

Authenticating with FloxHub

A pipeline that only uses an environment committed to the repository needs no credentials at all. You need to authenticate when the pipeline pulls a FloxHub environment, installs packages from a private catalog, or publishes. Give the pipeline its own identity rather than a person’s. Create a service account in your organization, issue it a token, and store that token as a secret on your CI platform. Set it in the FLOX_FLOXHUB_TOKEN environment variable, which the Flox CLI reads without a separate login step. Here that variable is filled from a GitHub Actions repository secret:

.github/workflows/ci.yml

jobs:
  build:
    runs-on: "ubuntu-latest"
    env:
      FLOX_FLOXHUB_TOKEN: ${{ secrets.FLOX_SERVICE_TOKEN }}
    steps:
      - uses: "flox/install-flox-action@v2"
      - uses: "flox/activate-action@v1"
        with:
          environment: my-org/my-env
          command: npm run build

The same variable works on any platform. In CircleCI set it as a project environment variable, and in GitLab set it as a masked CI/CD variable. A read-only service account can pull environments and install packages but cannot push or publish, so a leaked CI token cannot be used to change what the rest of the team installs. If you are running CI under your own identity, on a personal project for example, a personal access token works the same way. Note that it carries your full access, and revoking it also ends your own CLI sessions.

GitHub Actions

Flox provides two different actions that you can use in a GitHub Actions workflow:

flox/install-flox-action: This action installs the Flox CLI so you can run Flox commands as you would locally. At some point you would typically run flox activate -c "<your command>" with this action to run a command inside the Flox environment.
flox/activate-action: This action allows you to skip activating the environment yourself and simply provide the command that you would like to run in the environment.

Note that the flox/install-flox-action is still required if you want to use flox/activate-action. Here is an example workflow that installs the Flox CLI, runs npm run build inside the project’s environment, and runs netlify deploy inside a FloxHub environment:

.github/workflows/ci.yml

name: "CI"

...

jobs:

  build:
    name: "Build website"
    runs-on: "ubuntu-latest"
    steps:
      - name: "Checkout"
        uses: "actions/checkout@v4"

      - name: "Install Flox"
        uses: "flox/install-flox-action@v2"

      - name: "Build"
        uses: "flox/activate-action@v1"
        with:
          command: npm run build

      - name: Activate remote environment
        uses: flox/activate-action@v1
        with:
          environment: my-username/my-netlify-env
          command: netlify deploy

This is an example project; yours will probably look a little different. flox/install-flox-action installs the latest version of Flox, and flox/activate-action runs a command inside the Flox environment.

CircleCI

There is a Flox Orb that helps you use Flox inside CircleCI. Similar to GitHub Actions there is a flox/install step and a separate flox/activate step. Here is an example CircleCI workflow that installs Flox and runs npm run build inside the environment:

.circleci/config.yml

version: 2.1

orbs:
  flox: flox/orb@1.0.0

jobs:
  build:
    machine:
      image: ubuntu-2204:current
    steps:
      - checkout
      - flox/install
      - flox/activate:
          command: "npm run build"

The install step installs the latest Flox release by default; you can pin a specific release with the channel and version options. The activate step runs a command in the context of a Flox environment.

GitLab

To run Flox in a GitLab pipeline you use a container image with Flox preinstalled. Flox provides the ghcr.io/flox/flox image for you to use in your pipelines. Inside the container you have access to the full Flox CLI, so running a command in the container looks the same as it would locally: flox activate -c "<your command>". Here is an example GitLab pipeline that uses a Flox container to run npm run build inside the environment:

.gitlab-ci.yml

build:
  stage: build
  image: ghcr.io/flox/flox:latest
  script:
    - flox activate -c "npm run build"

The ghcr.io/flox/flox image comes with Flox already installed, so flox activate -c runs the command inside the Flox environment.

Suggestions

Now that you know how to use your Flox environment in CI/CD, the world is your oyster. Here are some suggestions for things you can do with your Flox environment in CI:

Run a linter to ensure that new changes adhere to your team’s style.
Use flox containerize to build a container from your environment to deploy elsewhere.
Build artifacts for multiple systems.
Run a link checker over your documentation.

Introduction

Install Flox

Quickstart

Tutorials

Imageless Kubernetes

Concepts

Languages

Customer

Running Flox in CI/CD

Authenticating with FloxHub

GitHub Actions

CircleCI

GitLab

Suggestions

Where to next?

​Authenticating with FloxHub

​GitHub Actions

​CircleCI

​GitLab

​Suggestions

​Where to next?

Authenticating with FloxHub

GitHub Actions

CircleCI

GitLab

Suggestions

Where to next?