save-artifact

Purpose

Upload a single build artifact (an APK, a tarball, a jar, …) and store it on the host under a directory you configure. The typical CI scenario: a job produces a release file and pushes it to a host so it can be served or picked up later, named by branch and job id.

Config

config/sbp-android.json (the file name matches the <name> segment in the URL):

JSON
YAML

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

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

Usage

curl \
  --data-binary @app/build/outputs/apk/release/app-release.apk \
  --fail \
  -H "api-key: $UPLOAD_KEY" \
  https://dc-agent.example.com/dc-agent/save-artifact/sbp-android/$CI_COMMIT_REF_NAME-$CI_JOB_ID

POST /dc-agent/save-artifact/{name}/{version} — the second-to-last segment ({name}) selects the config file; the last segment ({version}) becomes the stored file name.

Parameters

Name	Description	Default	Required
`dir`	Directory on the host where the file is written	—	yes
`extension`	Extension appended to the stored file	—	no
`replaceDirChars`	If set, every occurrence of this string in `{version}` is replaced with `/`, letting you write into sub-directories	—	no
`apiKeys`	Accepted secrets → owner labels	—	yes (without it every call gets 401)
`type`	`SAVE_ARTIFACT`; must match the endpoint — another type gets 401, a missing or misspelled one is accepted with a warning in the agent log	—	recommended

Request header x-dc-agent-file-extension overrides the configured extension for a single upload. It must be a plain extension — letters, digits, ., -, _, starting with a letter or digit, no .. (e.g. tar.gz, jar); anything else is rejected.

Result

The file lands at <dir>/<version>.<extension>. With the config above and a {version} of master-216018, the result is:

/opt/sbp-android/master-216018.apk

Success returns HTTP 200.
A {version} containing .. is rejected, and the final path must stay inside the canonical dir; {name} must be a valid command name — see Security.
A write failure returns HTTP 500; a missing or wrong api-key, an unknown {name} or a config of another type returns HTTP 401 before anything is written.