Jenkins构建时BUILD_TAG在docker-compose异常及解决方案原理咨询

The root cause of your issue lies in how docker-compose groups resources using project names, not just container names or workspace directories. Here's a detailed breakdown:

Default Project Name Behavior #

By default, docker-compose uses the basename of the directory containing your docker-compose.yml file as the project name. Since both your pipelines store their compose file in a directory named rails_docker (even across separate WORKSPACES), docker-compose assigned the same default project name (rails_docker) to both pipelines. This meant all resources from both runs were grouped under the same project, leading to cross-interference.

Why This Caused Your Observed Issues #

• Parallel pipeline conflicts: When you ran docker-compose up without -p, docker-compose would scan for existing resources (containers, networks) under the shared rails_docker project. It would then try to reconcile the current service definitions (with your pipeline's BUILD_TAG) against the existing ones from the other pipeline. Since container names didn't match, docker-compose would terminate the old containers (from the first pipeline) and create new ones with the current BUILD_TAG.
• Lagging BUILD_TAG output: The console output showing the older BUILD_TAG was docker-compose referencing existing containers from the shared project during this reconciliation process—even though your current pipeline's environment variable was correct.

Why -p ${BUILD_TAG} Resolves the Problem #

The -p flag explicitly sets a unique project name for each pipeline run using your BUILD_TAG. This creates a fully isolated namespace for each pipeline's resources:

• Each docker-compose command now operates on its own project, so changes in one pipeline have no impact on the other.
• Even if the directory structure inside each WORKSPACE is identical, the unique project name ensures containers, networks, and other resources are completely separated between runs.

Why Container Names Alone Weren't Enough #

While you defined unique container_name values, docker-compose relies on the project name to track which resources belong to a specific compose setup. Container names are just human-readable labels—they don't isolate resources into separate projects. Without a unique project name, docker-compose will manage all resources under the same group, leading to unexpected cross-pipeline modifications.

内容的提问来源于stack exchange，提问作者Theoran