Playbooks & Execution•5 min read•Workspace

Workspace File Manager & Templates

Upload, manage, and edit Jinja2 configuration templates, shell scripts, and deployment files directly in the browser.

Ansible automation relies heavily on supporting static assets: Jinja2 configuration templates (.j2), custom Nginx/database configs, shell scripts, SSL certificates, and application release tarballs. Managing these files outside your automation platform creates operational friction, requiring separate SFTP tools or direct SSH terminal sessions into the controller host.

CIEL provides a dedicated Playbook Files & Assets workspace (/files) under the Automation menu. It allows operators to upload, inspect, create, organize, and edit static project assets directly in the browser, with instant path references ready to paste into playbook tasks.

Workspace Playbook Files and Assets Explorer

1. Project Files Workspace

Each project in CIEL maintains an isolated asset filesystem rooted at <CIEL_HOME>/workspaces/<project_id>/files/. Files stored here belong exclusively to the active project workspace, preventing cross-project pollution or unintended overwrites.

The explorer view includes:

  • Breadcrumb Navigation: Jump through directory segments starting from the root files/ folder.
  • Search Filter: Search file names and relative paths within the current folder in real time.
  • Ansible Relative Path Badges: Every row displays the exact playbook reference path (such as files/deploy.sh or files/nginx.conf) with a one-click copy button.
  • File Metadata: Displays file type icons, byte size, and UTC last-modified timestamps.
  • Integrated Monaco Studio Editing: Clicking Edit on any text file (.j2, .conf, .sh, .yml, .json, .sql, .env, .service) opens the file directly in the Monaco code editor (/studio?file=<path>) with full syntax highlighting.

2. Asset Operations & Ingestion

The top toolbar provides four primary actions:

  • Upload File: Upload files from your local workstation directly into the active folder. Text and configuration files up to 15 MB can be edited in the browser, while larger binary archives can be stored for automated deployment.
  • New File: Create a new file with an initial template or blank content. Selecting this action generates the file and automatically redirects to Monaco Studio for authoring.
  • New Folder: Create nested directory structures (such as configs/, templates/, scripts/, or archives/) to keep large playbooks organized.
  • Refresh: Re-query the project files filesystem to detect files created dynamically by background jobs or CLI scripts.
  • Rename & Delete: Row action buttons allow maintaining file names and removing obsolete assets with immediate confirmation dialogs.

3. Playbook Integration Patterns

During job execution, CIEL automatically mounts the project files directory to the runner execution environment at project/playbooks/files. This allows tasks to reference assets using standard relative paths without hardcoding absolute host directories.

The dashboard includes six standard integration patterns:

Pattern 1: Deploy Static Configuration (ansible.builtin.copy)

Copy configuration files, daemon configurations, or certificates directly to managed hosts:

tasks/deploy_nginx.yml(yaml)
vars:
  local_config_file: "{{ playbook_dir }}/files/configs/nginx.conf"

tasks:
  - name: Deploy Nginx configuration
    ansible.builtin.copy:
      src: "{{ local_config_file }}"
      dest: /etc/nginx/nginx.conf
      owner: root
      group: root
      mode: "0644"

Pattern 2: Render Dynamic Template (ansible.builtin.template)

Process dynamic Jinja2 template files populated with variables from inventories, variable sets, and runtime parameters:

tasks/render_env.yml(yaml)
vars:
  template_source: "{{ playbook_dir }}/files/templates/app.env.j2"

tasks:
  - name: Render environment configuration
    ansible.builtin.template:
      src: "{{ template_source }}"
      dest: /opt/app/.env
      owner: appuser
      mode: "0600"

Pattern 3: Execute Local Script on Target (ansible.builtin.script)

Run a bash, sh, or Python script stored in CIEL directly on remote nodes without manually copying it first:

tasks/run_bootstrap.yml(yaml)
vars:
  bootstrap_script: "{{ playbook_dir }}/files/scripts/bootstrap.sh"

tasks:
  - name: Run initial node bootstrap script
    ansible.builtin.script: "{{ bootstrap_script }} --environment=production"
    args:
      creates: /var/log/bootstrap.done

Pattern 4: Unpack Release Archive (ansible.builtin.unarchive)

Extract tarballs, gzip archives, or application zip bundles stored in project files onto remote target directories:

tasks/extract_release.yml(yaml)
vars:
  app_bundle: "{{ playbook_dir }}/files/archives/app-dist.tar.gz"

tasks:
  - name: Extract prebuilt application release
    ansible.builtin.unarchive:
      src: "{{ app_bundle }}"
      dest: /var/www/html/
      remote_src: false

Pattern 5: Fetch Remote Artifacts (ansible.builtin.fetch)

Collect diagnostic bundles, database dumps, or access logs from remote hosts back into the CIEL project files tree. CIEL automatically creates any missing subdirectories:

tasks/fetch_logs.yml(yaml)
vars:
  backup_dir: "{{ playbook_dir }}/files/backups/{{ inventory_hostname }}"

tasks:
  - name: Fetch remote log to nested project files folder
    ansible.builtin.fetch:
      src: /var/log/nginx/access.log
      dest: "{{ backup_dir }}/"
      flat: true

Pattern 6: Create Folders in Playbook (ansible.builtin.file)

Playbooks can dynamically create directory structures inside the project files filesystem by delegating the task to localhost:

tasks/create_folder.yml(yaml)
vars:
  dated_folder: "{{ playbook_dir }}/files/reports/{{ ansible_date_time.date | default('daily') }}"

tasks:
  - name: Ensure target report folder exists in CIEL project files
    ansible.builtin.file:
      path: "{{ dated_folder }}"
      state: directory
      mode: "0755"
    delegate_to: localhost
    run_once: true

When launching a job, CIEL constructs an isolated workspace for that execution at <CIEL_HOME>/workspaces/<project_id>/jobs/<job_id>/.

To ensure performance and zero storage duplication, the runner links the canonical project assets:

  • Files Symlink: <job_workspace>/project/playbooks/files -> <CIEL_HOME>/workspaces/<project_id>/files
  • Roles Symlink: <job_workspace>/project/roles -> <CIEL_HOME>/runner/roles
  • Collections Symlink: <job_workspace>/project/collections -> <CIEL_HOME>/runner/collections

Path Conflict Detection

If CIEL_HOME is modified (for example, switching from a default container directory to a persistent host mount at /opt/ciel-data), existing project workspaces might retain symlinks pointing to the previous path.

Before executing any playbook, CIEL validates that all links resolve to the active controller directory. If an invalid or dangling target is detected, CIEL halts execution with an explicit error to prevent writing data to incorrect locations:

text
PlaybookFilesPathConflictError: Job playbook files symlink points to a different target: .../files -> /old/path/files

Remediation

To resolve stale symlink pointers after a path migration, remove the old symlink in the project directory:

bash
# Remove stale symlinks in the project workspace
rm -f /opt/ciel-data/workspaces/<project_id>/project/playbooks/files
rm -f /opt/ciel-data/workspaces/<project_id>/project/roles
rm -f /opt/ciel-data/workspaces/<project_id>/project/collections

On the next job launch, CIEL automatically detects the clean directory state and recreates the symlinks pointing to the active CIEL_HOME mount.


5. Official Ansible Documentation References

For additional module parameters, return values, and security best practices: