Introduction

When working with a CI/CD system, the user must keep its particularities in mind and integrate with the existing primitives and components.

werf provides a ready-made integrations for GitLab CI/CD and GitHub Actions. By leveraging CI jobs’ service environment variables, the integration does the following:

  • Creating a temporary Docker configuration based on the current user configuration and authorizing in the CI container registry.
  • Setting default values for werf commands:
    • Using the CI container registry (WERF_REPO).
    • Detecting the current environment (WERF_ENV).
    • Annotating the chart resources being deployed, binding to the CI system (WERF_ADD_ANNOTATION_*). Annotations are added to all resources being deployed, allowing the user to go to the bound pipeline, job, and commit if necessary.
    • Setting up werf logging (WERF_LOG_*).
    • Enabling automatic cleaning of werf processes for cancelled CI jobs (WERF_ENABLE_PROCESS_EXTERMINATOR=1). This procedure is only required in CI systems that cannot send termination signals to spawned processes (e.g., GitLab CI/CD).

Docker configuration

By default, werf ci-env copies the current Docker config directory (from ~/.docker or the path specified by --docker-config/WERF_DOCKER_CONFIG) to a temporary directory and exports the DOCKER_CONFIG environment variable pointing to it. This isolates CI job’s Docker operations from the host configuration.

The --use-docker-auth-config flag (or WERF_USE_DOCKER_AUTH_CONFIG=1) changes this behavior: instead of copying an existing Docker config, it creates a fresh one from the DOCKER_AUTH_CONFIG environment variable. This is useful when:

  • The CI runner doesn’t have a persistent Docker config (e.g., ephemeral runners).
  • Registry credentials are injected via DOCKER_AUTH_CONFIG (common in GitLab CI/CD).
  • You want a clean Docker config with no inherited credential helpers or settings.

The DOCKER_AUTH_CONFIG value must be a valid JSON string in Docker config format, e.g.:

{"auths": {"registry.example.com": {"auth": "base64-encoded-user:password"}}}

If --use-docker-auth-config is enabled but DOCKER_AUTH_CONFIG is not set, werf ci-env will exit with an error.

After creating the temporary config, if --login-to-registry is enabled (the default), werf ci-env additionally logs in to the CI container registry, adding credentials to the temporary config.

GitLab CI/CD

The entire integration boils down to invoking the ci-env command and then following the instructions the command prints to stdout.

. $(werf ci-env gitlab --as-file)

Then, within a shell session, all werf commands will use the preset values by default and work with the CI container registry.

For example, the pipeline stage to deploy to production might look as follows:

Deploy to Production:
  stage: deploy
  script:
    - . $(werf ci-env gitlab --as-file)
    - werf converge
  environment:
    name: production

If your CI runner provides registry credentials via the DOCKER_AUTH_CONFIG environment variable, you can use --use-docker-auth-config to create the Docker config from it:

Deploy to Production with Docker Auth Config:
  stage: deploy
  script:
    - . $(werf ci-env gitlab --as-file --use-docker-auth-config)
    - werf converge
  environment:
    name: production

You can find the complete .gitlab-ci.yml file for ready-to-use workflows, as well as the details of using werf with Shell, Docker, and Kubernetes executors, in the Getting started configurator by selecting CI/CD as your usage scenario and GitLab CI/CD as your CI/CD system, and choosing the CI runner type you need.

GitHub Actions

Just like with GitLab CI/CD, the integration boils down to invoking the ci-env command and then following the instructions the command prints to stdout.

. $(werf ci-env github --as-file)

Then, within a particular step, all werf commands will use the preset values by default and work with the CI container registry.

For example, the job to deploy to production might look as follows:

converge:
  name: Converge
  runs-on: ubuntu-latest
  steps:

    - name: Checkout code
      uses: actions/checkout@v3
      with:
        fetch-depth: 0

    - name: Install werf
      uses: werf/actions/install@v2

    - name: Run script
      run: |
        . $(werf ci-env github --as-file)
        werf converge
      env:
        WERF_KUBECONFIG_BASE64: ${{ secrets.KUBE_CONFIG_BASE64_DATA }}
        WERF_ENV: production
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

You can find the complete set of configurations (.github/workflows/*.yml) for the ready-to-use workflows in the Getting started configurator by selecting CI/CD as your usage scenario and GitHub Actions as your CI/CD system.