Integrate with CI and Automation Systems¶

Continuous Integration (CI) servers and build automation systems run automated test, build, and deployment pipelines. FlexVault includes flags and output options designed specifically for non-interactive execution inside automated build workers.

This guide explains how to configure fxv in automated environments, covers core automation use cases, and provides integration examples for popular build systems including Jenkins, TeamCity, GitHub Actions, GitLab CI, Azure DevOps, and CircleCI.

Automation CLI flags¶

When invoking fxv in scripts or automated pipelines, use the following global options to ensure predictable execution:

Platform version compatibility¶

FlexVault automation commands use standard shell execution and native pipeline syntax compatible across modern build systems:

Authentication and service accounts¶

Build workers operating on a shared repository require access to the underlying storage and an identity for attribution.

1. Storage Credentials. Pass S3 credentials to fxv init using --s3-access-key-id, --s3-secret-access-key, --s3-region, and --s3-http-endpoint. Store these credentials in your build system's secret store.
2. User Identity. Read-only operations such as fxv init and fxv sync do not require a logged-in user. If your CI job publishes build artifacts or automated updates, create a dedicated bot user with fxv user add and run fxv login <USERNAME> before executing fxv publish.

Workflow patterns for build workers¶

Automated jobs generally follow one of two workspace patterns:

fxv init s3://my-bucket/my-repo \
  --s3-access-key-id "$FXV_S3_KEY" \
  --s3-secret-access-key "$FXV_S3_SECRET" \
  --s3-region "$FXV_S3_REGION" \
  --unattended

fxv sync main.456 --unattended

fxv sync --unattended

Core automation use cases¶

Continuous integration and testing¶

The most common CI use case initializes a workspace on a build worker, syncs to a specific published revision or the tip of a branch, runs compilation and automated tests, and reports pass/fail status.

Pre-publish quality gating¶

Pipeline scripts can validate code formatting, linting, and security rules before allowing changes to be published to main. If test or lint steps fail, the pipeline exits with a non-zero status code, preventing automated publishing.

Automated release publishing¶

Build pipelines that generate compiled binaries, release packages, or generated documentation can automatically publish those outputs back to a central repository.

fxv login bot-release-builder --unattended
fxv snapshot -d "Build output for release v1.4.0" --unattended
fxv publish -d "Release build v1.4.0" --unattended

Scheduled repository maintenance¶

Repositories append metadata with every publish. To maintain optimal query performance, schedule a recurring maintenance job in your CI system to execute fxv repo optimize periodically (for example, nightly).

fxv repo optimize /path/to/repository quick --unattended

Event triggers and downstream integration¶

Automation scripts can poll or inspect revision metadata to trigger downstream deployment pipelines or send chat notifications.

LATEST_REVISION=$(fxv history --num 1 --published-only --format json | jq -r '.[0].revision_id')
echo "Latest published revision is ${LATEST_REVISION}"

Build system examples¶

Jenkins¶

In Jenkins (tested on Jenkins 2.x), store storage credentials in the Jenkins Credential Provider as secret text. Use withCredentials in a declarative Pipeline to inject credentials into shell steps.

pipeline {
    agent any

    environment {
        FXV_REPO = 's3://my-bucket/my-repo'
        FXV_REGION = 'us-east-1'
    }

    stages {
        stage('Checkout') {
            steps {
                withCredentials([
                    string(credentialsId: 'fxv-s3-key', variable: 'FXV_S3_KEY'),
                    string(credentialsId: 'fxv-s3-secret', variable: 'FXV_S3_SECRET')
                ]) {
                    sh '''
                        fxv init "${FXV_REPO}" \
                            --s3-access-key-id "${FXV_S3_KEY}" \
                            --s3-secret-access-key "${FXV_S3_SECRET}" \
                            --s3-region "${FXV_REGION}" \
                            --unattended
                        fxv sync --unattended
                    '''
                }
            }
        }

        stage('Build & Test') {
            steps {
                sh 'make build'
                sh 'make test'
            }
        }
    }
}

TeamCity¶

In TeamCity (tested on TeamCity 2020.1+), define environment variables for storage credentials in your Build Configuration settings (env.FXV_S3_ACCESS_KEY_ID and env.FXV_S3_SECRET_ACCESS_KEY) marked as password parameters.

Add a Command Line build step to initialize the workspace and sync to the target revision:

fxv init s3://my-bucket/my-repo \
  --s3-access-key-id "%env.FXV_S3_ACCESS_KEY_ID%" \
  --s3-secret-access-key "%env.FXV_S3_SECRET_ACCESS_KEY%" \
  --s3-region "us-east-1" \
  --unattended

fxv sync %build.vcs.number% --unattended

If your pipeline publishes build artifacts back to FlexVault from TeamCity, add a publish step:

fxv login bot-teamcity --unattended
fxv snapshot -d "Automated build artifact %build.number%" --unattended
fxv publish -d "Build artifact %build.number%" --unattended

GitHub Actions¶

In GitHub Actions (tested on Runner v2.x / ubuntu-latest), store S3 credentials in Repository Secrets (FXV_S3_ACCESS_KEY_ID and FXV_S3_SECRET_ACCESS_KEY).

name: CI Build

on:
  push:
    branches: [ main ]
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Install FlexVault
        run: |
          curl -fsSL https://fxv.dev/install.sh | sh
          echo "$HOME/.fxv/bin" >> $GITHUB_PATH

      - name: Initialize Workspace and Sync
        env:
          FXV_S3_KEY: ${{ secrets.FXV_S3_ACCESS_KEY_ID }}
          FXV_S3_SECRET: ${{ secrets.FXV_S3_SECRET_ACCESS_KEY }}
        run: |
          fxv init s3://my-bucket/my-repo \
            --s3-access-key-id "$FXV_S3_KEY" \
            --s3-secret-access-key "$FXV_S3_SECRET" \
            --s3-region us-east-1 \
            --unattended
          fxv sync --unattended

      - name: Run Tests
        run: cargo test

GitLab CI¶

In GitLab CI/CD (tested on GitLab 13.0+), set Masked and Protected CI/CD Variables for FXV_S3_ACCESS_KEY_ID and FXV_S3_SECRET_ACCESS_KEY under Project Settings.

stages:
  - build
  - test

default:
  before_script:
    - fxv init s3://my-bucket/my-repo --s3-access-key-id "$FXV_S3_ACCESS_KEY_ID" --s3-secret-access-key "$FXV_S3_SECRET_ACCESS_KEY" --s3-region us-east-1 --unattended
    - fxv sync --unattended

build-job:
  stage: build
  script:
    - make build

test-job:
  stage: test
  script:
    - make test

Azure DevOps¶

In Azure Pipelines (tested on Azure DevOps Services / Server 2020+), store credentials in Secret Variables within a Pipeline Variable Group.

trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

variables:
  - group: flexvault-credentials

steps:
  - script: |
      curl -fsSL https://fxv.dev/install.sh | sh
      echo "##vso[task.prependpath]$HOME/.fxv/bin"
    displayName: 'Install FlexVault'

  - script: |
      fxv init s3://my-bucket/my-repo \
        --s3-access-key-id "$(FXV_S3_ACCESS_KEY_ID)" \
        --s3-secret-access-key "$(FXV_S3_SECRET_ACCESS_KEY)" \
        --s3-region us-east-1 \
        --unattended
      fxv sync --unattended
    displayName: 'Initialize Workspace and Sync'

  - script: |
      cargo test
    displayName: 'Run Tests'

CircleCI¶

In CircleCI (tested on CircleCI 2.1+), store S3 credentials under Project Settings in Environment Variables (FXV_S3_ACCESS_KEY_ID and FXV_S3_SECRET_ACCESS_KEY).

version: 2.1

jobs:
  build-and-test:
    docker:
      - image: cimg/base:stable
    steps:
      - run:
          name: Install FlexVault
          command: |
            curl -fsSL https://fxv.dev/install.sh | sh
            echo 'export PATH="$HOME/.fxv/bin:$PATH"' >> $BASH_ENV
      - run:
          name: Initialize Workspace and Sync
          command: |
            fxv init s3://my-bucket/my-repo \
              --s3-access-key-id "$FXV_S3_ACCESS_KEY_ID" \
              --s3-secret-access-key "$FXV_S3_SECRET_ACCESS_KEY" \
              --s3-region us-east-1 \
              --unattended
            fxv sync --unattended
      - run:
          name: Run Tests
          command: cargo test

workflows:
  main-workflow:
    jobs:
      - build-and-test

Parsing status and revision metadata¶

When scripts need to inspect workspace state or revision information programmatically, pass --format json to receive machine-readable output.

For example, to extract the current published revision ID in a shell script using jq:

REVISION=$(fxv status --format json | jq -r '.parent_published_revision')
echo "Building revision: ${REVISION}"

To view revision details as JSON for auditing build inputs:

fxv changeinfo main.456 --format json