Securely Pass Github Secrets to Dockerfile: A Complete Guide (2026)

Passing sensitive information like API keys or service account credentials to a Dockerfile during a build process is a common requirement. However, ensuring these secrets remain secure and do not get exposed, especially in logs, is critical. In this guide, we will explore how to securely pass Github Secrets to a Dockerfile using Docker secrets and Github Actions, focusing on a practical use case involving the Google Cloud SDK setup.

Key Takeaways

• Understand the importance of securely handling secrets in Docker builds.
• Learn how to use Github Secrets with Docker without exposing them in logs.
• Set up a secure environment for Google Cloud SDK in a Dockerfile.
• Implement Docker secrets to keep sensitive data safe.

When working with Docker and Github Actions, it's crucial to handle secrets carefully to avoid security breaches. In this tutorial, you will learn how to pass a service-account.json securely to your Dockerfile without saving it to your repository, leveraging Docker secrets. This approach ensures that your secrets are not exposed in logs, providing a more secure way of handling them during builds.

Prerequisites

• Basic understanding of Docker and Dockerfiles.
• A Github repository with Github Actions enabled.
• Docker installed on your local machine (version 24.0 or later).
• Google Cloud SDK account and the necessary JSON key file.
• Familiarity with Github Secrets.

Step 1: Set Up Github Secrets

First, you need to add your service account JSON file as a secret in your Github repository. This ensures that the sensitive information does not get stored directly in your codebase.

1. Navigate to your Github repository.
2. Go to Settings > Secrets and variables > Actions.
3. Click New repository secret.
4. Name your secret (e.g., GCLOUD_SERVICE_ACCOUNT_JSON).
5. Paste the content of your JSON key file into the secret value field.
6. Click Add secret.

Step 2: Configure Dockerfile for Google Cloud SDK

Next, update your Dockerfile to include the Google Cloud SDK. Since we want to pass the secret securely, we'll use build arguments.

# Dockerfile
FROM google/cloud-sdk:latest

# Install necessary packages
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Copy the entrypoint script to the image
COPY entrypoint.sh /entrypoint.sh

# Make sure the script is executable
RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

Step 3: Create an Entrypoint Script

Create a script that will handle the authentication using the service account JSON passed as a secret. This script will be executed when the container starts.

#!/bin/bash

# Use the secret passed as an argument
echo "$GCLOUD_SERVICE_ACCOUNT_JSON" > /tmp/key.json

gcloud auth activate-service-account --key-file=/tmp/key.json

# Remove the key file after use
echo "Cleaning up key file"
rm /tmp/key.json

# Run the main process
exec "$@"

Step 4: Set Up Github Actions Workflow

Now, configure your Github Actions workflow to build and run the Docker image. Use the secret you stored earlier in the workflow.

# .github/workflows/docker-image.yml
name: Docker Image CI

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout repository
      uses: actions/checkout@v3

    - name: Set up Docker Buildx
      uses: docker/setup-buildx-action@v2

    - name: Login to DockerHub
      uses: docker/login-action@v2
      with:
        username: ${{ secrets.DOCKER_USERNAME }}
        password: ${{ secrets.DOCKER_PASSWORD }}

    - name: Build and push Docker image
      uses: docker/build-push-action@v4
      with:
        context: .
        push: true
        tags: user/repo:latest
        secrets: |  # Pass Github secret to Docker
          id=GCLOUD_SERVICE_ACCOUNT_JSON,src=/tmp/key.json

Common Errors/Troubleshooting

• Error: Cannot find key file: Ensure the entrypoint script has the correct path to the key file.
• Permission denied: Verify that the script is executable and the service account has the necessary permissions.
• Docker build fails: Check if the secret is correctly referenced in the Github Actions workflow.

Frequently Asked Questions

Why use Docker secrets instead of build arguments?

Docker secrets are more secure as they do not appear in the Docker build logs, unlike build arguments which can expose sensitive data.

Can I pass multiple secrets to a Dockerfile?

Yes, you can pass multiple secrets by specifying each one in the Github Actions workflow under the secrets section.

Is it safe to store secrets in Github?

Github encrypts secrets and only exposes them to workflows that run on the repository. Ensure you manage permissions appropriately.

Frequently Asked Questions

Why use Docker secrets instead of build arguments?

Docker secrets are more secure as they do not appear in the Docker build logs, unlike build arguments which can expose sensitive data.

Can I pass multiple secrets to a Dockerfile?

Yes, you can pass multiple secrets by specifying each one in the Github Actions workflow under the secrets section.

Is it safe to store secrets in Github?

Github encrypts secrets and only exposes them to workflows that run on the repository. Ensure you manage permissions appropriately.