Workspace Build Management: Jenkins And OTO

This guide defines workspace-level build guidance for Jenkins and OTO-backed build/deploy flows. It does not replace project-owned build commands.

Principles

Project-local commands are the source of truth for build behavior.
Jenkins may orchestrate shared or scheduled builds.
OTO may act as the build/deploy domain agent when a project explicitly uses OTO for that flow.
Credentials used by builds follow .workspace-ops/docs/secrets-sops.md.
Evidence should be reproducible without exposing private job URLs, tokens, or host secrets.

Responsibility Split

Area	Owner
Unit test/build commands	project repository
Shared scheduled execution	Jenkins, when configured
Build/deploy domain agent behavior	OTO, when configured
Remote runner environment	workspace inventory and project `agent-test/local`
Secret injection	project runtime plus SOPS/secret guide
Artifact naming and retention	project or Jenkins job, documented in project guide
Evidence logs	project task/review docs or workspace summary, without secrets

Jenkins Remote API With SOPS

Jenkins automation credentials are project-owned secrets. Store only encrypted material in the project repository, and keep decryption identities on the remote runner or operator machine.

Recommended encrypted keys:

Key	Purpose
`jenkins_url`	Base URL used by the automation runtime
`jenkins_username`	Jenkins user used for API calls
`jenkins_api_token`	Jenkins API token with the minimum job permissions

Recommended project layout:

Item	Location
SOPS policy	project root `.sops.yaml`
Encrypted CI secret	project-owned `secrets/*.sops.json` or existing project convention
Local age/GPG identity	ignored runner-local path, such as `$HOME/.config/sops/age/<project>-ci-key.txt`

API validation must not print decrypted values. Use a temporary file, load only the required keys, call a low-impact endpoint, and remove the temporary output.

export SOPS_AGE_KEY_FILE="$HOME/.config/sops/age/<project>-ci-key.txt"

secret_json="$(mktemp)"
secret_env="$(mktemp)"
trap 'rm -f "$secret_json" "$secret_env"' EXIT

sops -d secrets/<project>.ci.sops.json > "$secret_json"

python3 - "$secret_json" > "$secret_env" <<'PY'
import json
import shlex
import sys

payload = json.load(open(sys.argv[1]))
mapping = {
    "jenkins_url": "JENKINS_URL",
    "jenkins_username": "JENKINS_USERNAME",
    "jenkins_api_token": "JENKINS_API_TOKEN",
}
for source, target in mapping.items():
    print(f"{target}={shlex.quote(payload[source])}")
PY

. "$secret_env"

curl -sS --fail \
  --user "$JENKINS_USERNAME:$JENKINS_API_TOKEN" \
  "$JENKINS_URL/whoAmI/api/json" >/dev/null

For Jenkins POST calls, fetch a crumb when CSRF protection is enabled and pass it as a header. Keep the crumb in a shell variable; do not echo it to logs.

crumb_header="$(
  curl -sS --fail \
    --user "$JENKINS_USERNAME:$JENKINS_API_TOKEN" \
    "$JENKINS_URL/crumbIssuer/api/json" |
  python3 -c 'import json, sys; p=json.load(sys.stdin); print(p["crumbRequestField"] + ":" + p["crumb"])'
)"

curl -sS --fail -X POST \
  --user "$JENKINS_USERNAME:$JENKINS_API_TOKEN" \
  -H "$crumb_header" \
  -H "Content-Type: application/xml" \
  --data-binary @job-config.xml \
  "$JENKINS_URL/createItem?name=<job-name>"

Minimum Jenkins permissions depend on the operation. A thin job setup usually needs Job/Create, Job/Configure, Job/Build, and Job/Read. Artifact download validation needs Job/Read and artifact access for the selected job.

Tracked docs may record key names, encrypted file paths, job naming rules, and validation command classes. They must not record raw token values, decrypted payloads, private account values, or tokenized artifact URLs.

Project Guide Should Record

project build commands, such as bin/test, bin/lint, bin/build, or make test
Jenkins job class or naming rule if Jenkins is used
OTO role if OTO is used
artifact output path or naming convention
evidence location and minimum result fields
credential injection boundary, linked to the SOPS guide
remote runner requirements when local validation is insufficient

Evidence Fields

Build evidence should include:

command or Jenkins/OTO job class
project and branch/ref
environment class, such as local, remote runner, Jenkins, or OTO
result
artifact path or identifier class when applicable
follow-up action when failed

Do not include raw credential values or private tokenized URLs.

Safety Checklist

Project-local command is documented.
Jenkins/OTO responsibility does not override project source of truth.
Artifact and evidence paths are documented.
Build credentials are referenced through the SOPS/secret guide.
Remote runner assumptions match .workspace-ops/docs/remote-test-environments.md.

4.9 KiB Raw Blame History