There are lot of benefits to using Docker containers in CI/CD pipelines, especially for stateful systems like databases. For example, when you run integration tests, each CI job can start the database in an isolated container with a clean state, preventing conflicts between tests. This results in a testing environment that is reliable, consistent, and cost effective. This approach also reduces latency and improves the overall performance of the CI/CD pipeline because the database is locally accessible.

The Linux-based Azure Cosmos DB emulator is available as a Docker container and can run on a variety of platforms, including ARM64 architectures like Apple Silicon. It allows local development and testing of applications without needing an Azure subscription or incurring service costs. You can easily run it as a Docker container, and use it for local development and testing:

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview

Azure Cosmos DB + GitHub Actions

Let’s walk through an example to better understand how to use Azure Cosmos DB emulator with GitHub Actions, which is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline using workflows. A workflow is a configurable automated process that can run one or more jobs. It is defined by a YAML file checked in to your repository and runs when triggered by an event in your repository, or they can be triggered manually, or at a defined schedule.

Example: CI workflow for a .NET application

This GitHub Actions workflow configures Azure Cosmos DB Linux-based emulator as a GitHub actions service container as part of a job. GitHub takes care of starting the Docker container and destroys it when the job completes – no manual intervention required (such as executing the docker run command).

name: .NET App CI

on:
  push:
    branches: [main]
    paths:
      - 'dotnet-app/**'
  pull_request:
    branches: [main]
    paths:
      - 'dotnet-app/**'

jobs:
  build-and-test:
    runs-on: ${{ matrix.os }}

    strategy:
      matrix:
        os: [ubuntu-latest, ubuntu-24.04-arm]

    services:
      cosmosdb:
        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
        ports:
          - 8081:8081
        env:
          PROTOCOL: https

    env:
      COSMOSDB_CONNECTION_STRING: ${{ secrets.COSMOSDB_CONNECTION_STRING }}
      COSMOSDB_DATABASE_NAME: ${{ vars.COSMOSDB_DATABASE_NAME }}
      COSMOSDB_CONTAINER_NAME: ${{ vars.COSMOSDB_CONTAINER_NAME }}

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

      - name: Set up .NET
        uses: actions/setup-dotnet@v3
        with:
          dotnet-version: '8.0.x'

      - name: Export Cosmos DB Emulator Certificate
        run: |
          sudo apt update && sudo apt install -y openssl
          openssl s_client -connect localhost:8081 </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cosmos_emulator.cert
          
          sudo cp cosmos_emulator.cert /usr/local/share/ca-certificates/
          sudo update-ca-certificates

      - name: Install dependencies
        run: cd dotnet-app && dotnet restore

      - name: Build
        run: cd dotnet-app && dotnet build --no-restore

      - name: Run tests
        run: cd dotnet-app && dotnet test --no-build --verbosity normal

This job is configured to run on an Ubuntu runner and uses the mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview docker image as a service container. The connection string, database name, and container name are configured as environment variables. Since the job runs directly on a GitHub Actions hosted runner, the Run tests step can access the emulator using localhost:8081.

Try it out!

This GitHub repository provides examples of how to configure the Linux emulator as part of a GitHub Actions CI workflow for .NET, Python, Java and Go applications on both x64 and ARM64 architectures (demonstrated for Linux runner using ubuntu).

Fork the repository

Navigate to the GitHub repository, and click the Fork button at the top-right corner of the repository page to create a copy of the repository under your own GitHub account.

In your GitHub account, open the repository and make sure to enable workflows in the repository settings.

Add the Cosmos DB emulator connection string (COSMOSDB_CONNECTION_STRING) as Repository secret to the repository. Use the following value:

AccountEndpoint=http://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

Add database name (COSMOSDB_DATABASE_NAME) and container name (COSMOSDB_CONTAINER_NAME) as Repository variables:

Clone the forked repository to your local machine (make sure to use your GitHub username):

git clone https://github.com/<your-username>/cosmosdb-linux-emulator-github-actions.git

cd cosmosdb-linux-emulator-github-actions

Trigger the workflow

To trigger the workflow, make a small change to any/all of the code (.NET, Java, Python, or Go), add and commit your changes. For easier understanding, separate workflows are used for each language.

Push your changes to your forked repository on GitHub:

git add .

git commit -m "Your commit message"

git push origin main

After pushing the changes, GitHub Actions will automatically run the workflow. Go to the Actions tab in your repository to see the status and results of the workflows. Review any logs or output to ensure the workflows are running correctly.

GitHub Actions runner considerations

The sample repository demonstrated ubuntu based runners (for x64 and ARM64 architectures). This should work for Windows ARM-based runners as well. If you are considering Windows x64 runners, note that at the time of writing, GitHub Actions service containers are not supported in non-Linux runners. But you can work around this by adding steps to install Docker, and manage its lifecycle including starting and stopping the container.

Wrap up

As I mentioned earlier, there are a lot of benefits of using Docker container in CI pipelines. GitHub Actions was used as the CI/CD platform in this case, but these concepts apply to other solutions as well. Try it out and let us know what you think!

Leave a review

Tell us about your Azure Cosmos DB experience! Leave a review on PeerSpot and we’ll gift you $50. Get started here.

About Azure Cosmos DB

Azure Cosmos DB is a fully managed and serverless NoSQL and vector database for modern app development, including AI applications. With its SLA-backed speed and availability as well as instant dynamic scalability, it is ideal for real-time NoSQL and MongoDB applications that require high performance and distributed computing over massive volumes of NoSQL and vector data.

Try Azure Cosmos DB for free here. To stay in the loop on Azure Cosmos DB updates, follow us on X, YouTube, and LinkedIn.