Configuration

Where config lives

The agent loads one config file per task from CONFIG_DIR (default ./config). The file name matches the task name in the request URL: a request to /dc-agent/save-artifact/<name>/... loads config/<name>.json.

Both JSON and YAML are accepted — the loader tries config/<name>.json first and falls back to config/<name>.yml.

Two endpoints use a fixed, shared config file rather than a per-name one:

• fetch-url always loads config/fetch-url.json.
• docker/push and docker/check always load config/dc-docker.json (the {name} in the URL is the service name, not the config file name).

Note

Each config may carry a type field — ZIP_ARCHIVE, ZIP_DIRS, ZIP_ARCHIVE_VERSION, SAVE_ARTIFACT, FETCH_URL, JAR, WAR, NODE or DOCKER, the endpoint the command is called through (commands created via the operator always have it). A config of another type is refused with 401, so a key of a save-artifact command cannot drive /zip-archive/ with the same name. A config without type is still accepted, with a warning in the agent log — add the field. Spell the value exactly: an unknown value (a typo such as save-artifact) is read as no type at all and is accepted the same way, with the same warning.

Command names (the file name without extension) may contain only 0-9 a-z A-Z . _ - and no ..; a request for any other name gets 401.

The api-key model

Every authenticated config has an apiKeys object:

{
  "apiKeys": {
    "s3cr3t-value-the-caller-sends": "gitlab-ci"
  }
}

• The map key is the shared secret. The caller must send it in the api-key request header (or as the password of an HTTP Basic Authorization header).
• The map value is only a human-readable label identifying who owns that key. It is never matched against anything.
• Keys are stored in plaintext — anyone who can read config/*.json can read every live secret. Restrict file permissions and keep the config directory off shared storage.

You can list several keys to rotate or to identify multiple callers:

{
  "apiKeys": {
    "key-for-gitlab": "gitlab-ci",
    "key-for-jenkins": "jenkins"
  }
}

No apiKeys means no access

A config without an apiKeys object (or with an empty one) refuses every request with 401. See Security for the full auth model.

A complete annotated example

A save-artifact config, shown in both formats, with each field explained below. JSON has no comments, so the annotations follow in the table; in YAML you can inline them instead:

JSON

config/sbp-android.json

{
  "type": "SAVE_ARTIFACT",
  "apiKeys": {
    "REPLACE_WITH_A_LONG_RANDOM_SECRET": "gitlab-ci"
  },
  "dir": "/opt/sbp-android",
  "extension": "apk"
}

YAML

config/sbp-android.yml

type: SAVE_ARTIFACT
apiKeys:
  REPLACE_WITH_A_LONG_RANDOM_SECRET: gitlab-ci
dir: /opt/sbp-android
extension: apk

Field	Meaning
type	The endpoint this command is called through (see the note above).
apiKeys	Accepted secrets → owner labels (see above).
dir	Directory on the host where the uploaded file is written.
extension	File extension appended to the stored artifact.

Each command page documents the fields its own config accepts. For the full deploy-family parameter list, see the parameter reference.