Configure flow execution

Flows use agents to execute tasks.

• Flows executed from the GitLab UI use CI/CD.
• Flows executed in an IDE run locally.

You can configure the environment where flows use CI/CD to execute. You can also use your own runners, and specify variables in your jobs.

Executor architecture

When a flow runs in CI/CD, the runner:

1. Downloads the @gitlab/duo-cli package from the npm registry.
2. Runs the GitLab Duo CLI, which uses WebSocket to connect to the GitLab Duo Workflow Service.
3. Executes tools (file operations, Git commands) as directed by the AI model.

The executor version is managed by GitLab and updated as part of regular releases.

Configure CI/CD execution

To customize how flows are executed in CI/CD, create an agent configuration file in your project.

For a list of supported keys and their types, see the agent-config.yml reference.

Create the agent configuration file

1. In your project’s repository, create a .gitlab/duo/ folder.
2. In the folder, create a configuration file named agent-config.yml.
3. Add your required configuration options.
4. Commit and push the file to your default branch.

The configuration is applied when flows run in CI/CD for your project.

For an example of a complete agent-config.yml file, see the agent-config.yml reference.

Configure setup scripts

You can define setup scripts that run before your flow executes. This is useful for installing dependencies, configuring environments, or initialization.

To add setup scripts, in the agent-config.yml file, add the following commands:

setup_script:
  - apt-get update && apt-get install -y curl
  - pip install -r requirements.txt
  - echo "Setup complete"

These commands complete the following actions:

• Run before the main workflow commands.
• Execute in the order specified.
• Can be a single command or an array of commands.

The user context for setup_script depends on the Docker image. The default GitLab image runs as root. Custom images run as the user defined in the image’s USER directive. If your setup_script requires root access (for example, to install system packages), ensure your custom image is configured accordingly.

Configure caching

To configure caching to speed up subsequent flow runs, configure the agent-config.yml file to preserve files and directories between executions. Caching can be useful for dependency folders like node_modules or Python virtual environments.

Basic cache configuration

To cache specific paths, add the following to your agent-config.yml file:

cache:
  paths:
    - node_modules/
    - .npm/

Cache with keys

You can use cache keys to create different caches for different scenarios. Cache keys help ensure that the cache is based on your project’s state.

Use a string key

cache:
  key: my-project-cache
  paths:
    - vendor/
    - .bundle/

Use file-based cache keys

Create dynamic cache keys based on file contents (like lock files). When these files change, a new cache is created. This generates a SHA checksum of the specified files:

cache:
  key:
    files:
      - package-lock.json
      - yarn.lock
  paths:
    - node_modules/

Use a prefix with file-based keys

Combine a prefix with the SHA computed for the cache key files:

cache:
  key:
    files:
      - package-lock.json
    prefix: $CI_JOB_NAME
  paths:
    - node_modules/
    - .npm/

In this example, if the job name is test and the SHA checksum is abc123, the cache key becomes test-abc123.

Cache limitations

• You can specify up to two files for cache key generation. If more files are specified, only the first two are used.
• The cache paths field is required. A cache configuration without paths has no effect.
• Cache keys support CI/CD variables in the prefix field.

Configure ID tokens

To authenticate with third-party services from a flow, configure ID tokens.

ID tokens are JSON web tokens (JWT) that GitLab CI/CD generates and injects into the job that runs the flow for keyless OpenID Connect (OIDC) authentication without storing long-lived credentials. For example, you can use ID tokens to retrieve secrets from a secrets manager or sign binaries and Git commits.

To configure ID tokens, in the agent-config.yml file, add an id_tokens block. Each token requires an aud (audience) claim:

id_tokens:
  VAULT_ID_TOKEN:
    aud: https://vault.example.com

network_policy:
  allowed_domains:
    - vault.example.com

The aud claim can be a single string or a list of strings:

id_tokens:
  MY_ID_TOKEN:
    aud:
      - https://first.service.example.com
      - https://second.service.example.com

network_policy:
  allowed_domains:
    - first.service.example.com
    - second.service.example.com

Each token is available in the flow job as an environment variable that uses the name of the token. For the previous examples, the flow can use $VAULT_ID_TOKEN and $MY_ID_TOKEN.

If a token name matches a variable name declared elsewhere in your configuration, the ID token takes precedence.

For more information about the token payload and how to configure trust with third-party services, see OpenID Connect (OIDC) authentication using ID tokens.

Configure runners to execute flows

Flows that use CI/CD run on runners.

On GitLab.com, flows can use hosted runners, which GitLab provides. These are enabled by default.

You also have the option to configure your own runner for flows.

To configure your own runner for flows:

1. Create an instance runner or a group runner assigned to the top-level group. If you want flows to use project runners or group runners assigned to a subgroup, turn off the duo_runner_restrictions feature flag (GitLab Self-Managed only).
2. Add the gitlab--duo tag to the runner so that it picks up jobs for flows. If the runner does not have this tag, jobs with flows remain queued indefinitely. Use any of the following methods:

   • When you create the runner, in the Tags field, enter gitlab--duo.

   • For an existing runner, edit the jobs the runner can run and enter gitlab--duo in the Tags field.

   • If you configure runners with a config.toml file, add the tag to the [[runners]] section:

     [[runners]]
       executor = "docker"
       tags = ["gitlab--duo"]

3. Configure the runner to use an executor that supports Docker images, like docker, docker-autoscaler, or kubernetes. The shell executor is not supported.
4. If your top-level group has turned on IP address restrictions, add the runner’s IP address to your group’s IP allowlist so the runner can access the group.
5. GitLab Self-Managed only. Ensure the runner can reach the services that flows require:
   • Allow outbound connections from the GitLab instance to the Agent Platform.
   • Allow outbound connections from the runner to the Agent Platform.
   • For instances with self-signed certificates in the certificate chain, complete the additional GitLab Duo CLI configuration.

Use the execution environment sandbox to secure flows

For network and file system isolation, use the execution environment sandbox to secure flows executed on runners.

To use the sandbox, you must use one of the following images:

• Default Docker base image for the Agent Platform
• A custom image with SRT installed

To configure runners to use the sandbox, set privileged = true in your runner configuration.

For example:

[[runners]]
  executor = "docker"
  tags = ["gitlab--duo"]
  [runners.docker]
    privileged = true

You cannot use the sandbox with the following images:

• Custom images without SRT installed
• Hardened UBI 9 Minimal image