fix(docker-images): fail build when base image lacks the airbyte user

[devin-ai-integration]

What

Preventative guard for the failure class in https://github.com/airbytehq/oncall/issues/13302.

Related to https://github.com/airbytehq/oncall/issues/13302:

• https://github.com/airbytehq/oncall/issues/13302

Public mirror: #84351. See also #84349 and the pin bump #84350.

The connector Dockerfiles end with USER airbyte, but that OS user is created in the base image. Connectors pinning an old connectorBuildOptions.baseImage (e.g. source-declarative-manifest:5.15.0, which predates the user) build successfully — Docker records USER in the image config without validating it — and then fail at docker run with exit 125 and unable to find user airbyte: no matching entries in passwd file, which never mentions the base-image pin. That opaque failure is what broke the pre-release publish workflow, the regression harness, and per-connector image/spec checks.

How

Assert the user exists at build time, immediately before switching to it, in all three connector Dockerfiles:

RUN if ! id -u airbyte >/dev/null 2>&1; then \
        echo "ERROR: base image ${BASE_IMAGE} does not contain the airbyte user. Bump connectorBuildOptions.baseImage in the connector's metadata.yaml." >&2; \
        exit 1; \
    fi

Dockerfile.manifest-only-connector and Dockerfile.java-connector needed ARG BASE_IMAGE re-declared after FROM so the message can name the offending pin. One RUN layer, no extra image content.

This layer was chosen over a CDK-side error translation (airbyte_cdk.utils.docker.verify_connector_image) or a metadata QA check because the Dockerfiles are the single point every build path goes through — Gradle, airbyte-cdk image build (which downloads these templates from master when the monorepo isn't checked out), and CI — and it's the only place that can catch it deterministically without pulling and inspecting the remote base image separately.

Review guide

1. docker-images/Dockerfile.manifest-only-connector, Dockerfile.python-connector, Dockerfile.java-connector — the guard.
2. docker-images/test-manifest-only-connector-base-image-user.sh — new test: builds source-pokeapi against source-declarative-manifest:5.15.0 and asserts the build fails with the actionable message, then builds against :latest and asserts success.
3. .github/workflows/docker-connector-base-image-tests.yml — runs that test in the manifest-only job (already triggered by changes to these Dockerfiles).
4. docker-images/README.md — FAQ entry.

Verified locally on linux/amd64: the 5.15.0 build fails with

ERROR: base image docker.io/airbyte/source-declarative-manifest:5.15.0 does not contain the airbyte user. Bump connectorBuildOptions.baseImage in the connector's metadata.yaml.

and the :latest build succeeds. The Python and Java connector guards were not exercised locally — building the Python base image currently fails on an unrelated Debian package version mismatch (poppler-utils / libpoppler126) and the Java path needs a Gradle tarball, so those two rely on CI. Their base images do define the user today, so the guard is a no-op there.

User Impact

Connector developers and CI get a build-time failure naming the stale pin instead of an opaque exit 125 at container start. No runtime behavior change for published connectors.

Follow-up considered and skipped: a metadata lint for base-image pins far behind the current SDM release. .github/workflows/connectors-up-to-date.yml already runs airbyte-ops local connector bump-base-image across support levels, so staleness is largely covered.

Can this PR be safely reverted and rolled back?

• YES 💚

Link to Devin session: https://app.devin.ai/sessions/ca238921c33246d09d908bb694bcd05f

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

PR Slash Commands

Airbyte Maintainers (that's you!) can execute the following slash commands on your PR:

• 🛠️ Quick Fixes
  • /format-fix - Fixes most formatting issues.
  • /bump-version - Bumps connector versions, scraping changelog description from the PR title.
    • Bump types: patch (default), minor, major, major_rc, rc, promote.
    • The rc type is a smart default: applies minor_rc if stable, or bumps the RC number if already RC.
    • The promote type strips the RC suffix to finalize a release.
    • Example: /bump-version type=rc or /bump-version type=minor
  • /bump-progressive-rollout-version - Alias for /bump-version type=rc. Bumps with an RC suffix and enables progressive rollout.
• ❇️ AI Testing and Review (internal link: AI-SDLC Docs):
  • /ai-prove-fix - Runs prerelease readiness checks, including testing against customer connections.
  • /ai-canary-prerelease - Rolls out prerelease to 5-10 connections for canary testing.
  • /ai-review - AI-powered PR review for connector safety and quality gates.
• 📝 AI Documentation:
  • /ai-docs-review - AI-powered documentation review for PRs with connector changes.
  • /ai-create-docs-pr - Creates a documentation PR for connector changes, stacked on the current PR.
• 🚀 Connector Releases:
  • /publish-connectors-prerelease - Publishes pre-release connector builds (tagged as {version}-preview.{git-sha}) for all modified connectors in the PR.
  • /enable-autopilot-rollouts - Enables autopilot progressive rollouts for the modified connector(s) in the PR, remediating "autopilot rollouts not enabled for {connector-name}" auto-merge blockers. Sets defaultRolloutMode: autopilot and enableProgressiveRollout: true, preserving any existing autopilotConfig.
    • Optional args: connector=<CONNECTOR_NAME> (defaults to the modified connectors in the PR), strategy=fast|slow|default (defaults to fast).
    • Example: /enable-autopilot-rollouts or /enable-autopilot-rollouts connector=source-faker strategy=slow
• ☕️ JVM connectors:
  • /update-connector-cdk-version connector=<CONNECTOR_NAME> - Updates the specified connector to the latest CDK version.
    Example: /update-connector-cdk-version connector=destination-bigquery
• 🐍 Python connectors:
  • /poe connector source-example lock - Run the Poe lock task on the source-example connector, committing the results back to the branch.
  • /poe source example lock - Alias for /poe connector source-example lock.
  • /poe source example use-cdk-branch my/branch - Pin the source-example CDK reference to the branch name specified.
  • /poe source example use-cdk-latest - Update the source-example CDK dependency to the latest available version.
• ⚙️ Admin commands:
  • /force-merge reason="<REASON>" - Force merges the PR using admin privileges, bypassing CI checks. Requires a reason.
    Example: /force-merge reason="CI is flaky, tests pass locally"

📚 Show Repo Guidance

Helpful Resources

• Breaking Changes Guide - Breaking changes, migration guides, and upgrade deadlines
• Developing Connectors Locally
• Managing Connector Secrets
• On-Demand Regression Tests
• #connector-ci-issues
• #connector-publish-updates
• #connector-build-statuses

📝 Edit this welcome message.