There are many 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:

Dockerfile

  

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

Azure Cosmos DB With 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 into your repository and runs when triggered by an event in your repository, or it 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 is 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.

The Export Cosmos DB Emulator Certificate step is specific to .NET (as well as Java) applications because at the time of writing, the .NET and Java SDKs do not support HTTP mode in emulator. The PROTOCOL environment variable is set to https in the services section and this step exports the emulator certificate and adds them to the operating system trusted certificate store.

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 a repository secret to the repository. Use the following value:

Plain Text

  

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

Forking the repository

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

Add the database and container names as repository variables

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

Plain Text

 

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), and add and commit your changes. For easier understanding, separate workflows are used for each language.

Push your changes to your forked repository on GitHub:

Plain Text

  

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.

Review logs

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 to using Docker containers 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!

Similar Posts