gitfile

� Story / Motivation

Managing environment files can be difficult, especially across multiple services and environments.

To simplify this, I store my environment files in a private GitHub repository and use a GitHub personal access token to securely download them at runtime. This Docker image automates that process and makes it easy to use those files in Docker-based workflows and other environments.

�🚀 Features

• Fetch files or directories from any GitHub repository
• Supports branches, tags, and commit SHAs
• Recursive directory fetching
• Exact path preservation
• Built-in retry logic
• Minimal Alpine-based image
• Ideal for CI/CD and containerized workflows

🐳 Docker Image

thefoxiedk/gitfile:latest

Pull the image

docker pull thefoxiedk/gitfile:latest

▶️ Usage

docker run --rm \
  -e GITHUB_TOKEN=ghp_xxx \
  -e GITHUB_REPO=org/repo \
  -e GITHUB_PATHS=env/.prod,secrets/app.json \
  -e GITHUB_REF=main \
  -v $(pwd)/secrets:/secrets \
  thefoxiedk/gitfile:latest

Fetched files will be written to the mounted output directory.

Docker Compose Example

You can use this image with Docker Compose to fetch files automatically.

volumes:
  env-dir:

services:
  fetch-env:
    image: thefoxiedk/gitfile:latest
    container_name: fetch-env
    environment:
      GITHUB_TOKEN: ${GITHUB_TOKEN}
      GITHUB_REPO: ${GITHUB_REPO}
      GITHUB_PATHS: ${GITHUB_PATHS}
    volumes:
      - env-dir:/secrets
  env-printer:
    image: alpine:latest
    depends_on:
      fetch-env:
        condition: service_completed_successfully
    volumes:
      - env-dir:/output:ro
    # use as .env
    command: sh -c "cp /output/${PROJECT}/env.prod .env && cat .env"

    # export env vars and print
    # command: sh -c "export $(grep -v '^#' /output/${PROJECT}/env.prod | xargs) && env"

🔐 Required Environment Variables

⚙️ Optional Environment Variables

📁 Path Mapping (IMPORTANT)

GITHUB_PATHS are preserved exactly in the output.

The directory and file structure from the GitHub repository is mirrored 1:1 under OUT_DIR.

Example

GITHUB_PATHS=env/.prod,secrets/app.json
OUT_DIR=/secrets

Output

/secrets/
├─ env/
│  └─ .prod
└─ secrets/
   └─ app.json

• No renaming
• No flattening
• Safe for predictable mounts and automation

🧠 How It Works

1. Resolves the commit SHA from GITHUB_REF
2. Fetches the full repository tree via GitHub API
3. Filters files matching GITHUB_PATHS
4. Downloads contents using the Contents API
5. Decodes and writes files to disk preserving paths

🔒 Security Notes

• Use read-only GitHub tokens
• Never bake secrets into images
• Mount output directories as volumes
• Avoid logging sensitive content

📜 License

MIT