Understanding Drone CI's Execution Model

Pipeline as Containers

Each Drone CI pipeline step runs in a separate container. These containers share a common workspace mounted at /drone/src, which is the working directory for all steps. Drone creates this workspace dynamically and mounts it into all containers unless explicitly overridden.

Volume and Workspace Behavior

The workspace can persist artifacts across steps. However:

• Improper cleanup between steps can cause leftover files to affect downstream logic
• Race conditions may occur if parallel steps mutate shared files without synchronization
• File permission mismatches between host and containerized steps often go unnoticed until deployment

Common Failure Symptoms

1. Intermittent Step Failures

Steps randomly fail due to missing or corrupted intermediate files—especially when rerunning failed jobs.

2. Artifacts Persisting Across Pipelines

Misconfigured volumes or caching layers result in old build outputs polluting fresh pipelines.

3. Workspace Mount Conflicts

Custom plugins that redefine workspace mounts (e.g., for nested containers or dind) break assumptions and lead to "file not found" errors in sibling steps.

Root Cause Analysis

Misuse of Shared Workspace

Drone assumes a linear pipeline with shared file access. When users introduce custom volume mounts or run steps in parallel without coordination, race conditions and data inconsistencies emerge.

Improper Cache Configuration

Persistent cache mounts (e.g., /root/.cache, node_modules) can leak state across runs if not isolated per branch or commit hash. This causes builds to pass locally but fail in CI.

Unintended Permissions Issues

By default, Drone containers run as root. If artifacts are written with restrictive permissions, downstream steps running as non-root (common in enterprise compliance setups) will fail silently or throw access errors.

Step-by-Step Troubleshooting

1. Inspect the Workspace Lifecycle

Add debug steps to log file tree state before and after each critical step:

- name: debug-tree
  image: alpine
  commands:
    - ls -alhR /drone/src

This helps detect whether files are unexpectedly removed, renamed, or overwritten.

2. Isolate Cache by Scope

Use per-branch or per-commit identifiers when declaring caches:

- name: restore-cache
  image: drillster/drone-volume-cache
  settings:
    restore: true
    mount:
      - .npm
    path: /drone/src
    key: npm-cache-${DRONE_BRANCH}

3. Sanitize Between Steps

Explicitly clean up intermediate files when they're no longer needed:

- name: cleanup
  image: alpine
  commands:
    - rm -rf ./build /tmp/*

This prevents data bleed into other jobs or steps.

4. Validate Volume Paths

When using custom plugins or Docker-in-Docker (dind), inspect whether additional volumes unintentionally shadow /drone/src:

volumes:
  - name: docker-socket
    host:
      path: /var/run/docker.sock

Use unique mount paths to avoid collision with workspace volume.

5. Monitor with Drone Logs and Exit Codes

Drone provides per-step logs and exit codes. Use DRONE_LOGS_DEBUG=true in the server to trace what files are being written and which steps access them.

Best Practices for Stable Drone CI Pipelines

Structure Pipelines Linearly

Favor sequential steps with well-defined handoff points. Use environment variables or artifacts rather than implicit file sharing.

Use Plugins with Scoped Access

Use plugins that support scoped mounts and avoid assuming root-level access unless required. Check for mount and userID compatibility.

Secure and Cleanup Workspaces

Remove secrets, credentials, or build artifacts at the end of a pipeline, especially in public repositories or multi-tenant CI environments.

Adopt Artifact Stores for State

Use external artifact repositories (e.g., S3, Nexus) for handoffs between pipelines or stages. Avoid relying solely on local workspace for persistence.

Conclusion

Drone CI offers fast, container-native pipelines, but shared workspace handling requires careful management to avoid unpredictable failures. Misconfigured volumes, insufficient isolation, or overlooked permissions often cause flaky builds that erode confidence in CI. By adopting strict pipeline hygiene, isolating cache and workspace usage, and using external artifact management where appropriate, teams can build reliable and maintainable Drone CI pipelines even at enterprise scale.

FAQs

1. Why do my Drone steps fail intermittently even if they succeed locally?

Local environments often lack the workspace isolation present in Drone CI. Unclosed file handles, race conditions, or residual state can lead to non-reproducible builds.

2. Can I use parallel steps in Drone without conflict?

Yes, but only if parallel steps do not write to shared directories. Isolate paths or use separate volume mounts to prevent contention.

3. How do I debug shared workspace issues?

Insert logging steps (e.g., tree, stat) before and after critical operations to verify file states. Use DRONE_LOGS_DEBUG to increase logging granularity.

4. Is it safe to use Docker-in-Docker in Drone pipelines?

It is possible but risky. Mounting the Docker socket or using DinD can break workspace isolation and introduce host-level risks if not sandboxed properly.

5. What alternatives exist for long-term artifact sharing across pipelines?

Use external artifact stores like S3, GCS, or Nexus. These allow secure, reproducible artifact exchange between builds without relying on ephemeral workspaces.