docker pull mcr.microsoft.com\/cosmosdb\/linux\/azure-cosmos-emulator:vnext-preview<\/code><\/pre>\nAzure Cosmos DB + GitHub Actions<\/h2>\n
Let\u2019s walk through an example to better understand how to use Azure Cosmos DB emulator with\u00a0GitHub Actions<\/a>, 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\u00a0workflow\u00a0is 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.<\/p>\nExample: CI workflow for a .NET application<\/h3>\n
This GitHub Actions workflow configures Azure Cosmos DB Linux-based emulator as a\u00a0GitHub actions service container<\/a>\u00a0as part of a job. GitHub takes care of starting the Docker container and destroys it when the job completes \u2013 no manual intervention required (such as executing the\u00a0docker run command).<\/p>\nname: .NET App CI\r\n\r\non:\r\n push:\r\n branches: [main]\r\n paths:\r\n - 'dotnet-app\/**'\r\n pull_request:\r\n branches: [main]\r\n paths:\r\n - 'dotnet-app\/**'\r\n\r\njobs:\r\n build-and-test:\r\n runs-on: ${{ matrix.os }}\r\n\r\n strategy:\r\n matrix:\r\n os: [ubuntu-latest, ubuntu-24.04-arm]\r\n\r\n services:\r\n cosmosdb:\r\n image: mcr.microsoft.com\/cosmosdb\/linux\/azure-cosmos-emulator:vnext-preview\r\n ports:\r\n - 8081:8081\r\n env:\r\n PROTOCOL: https\r\n\r\n env:\r\n COSMOSDB_CONNECTION_STRING: ${{ secrets.COSMOSDB_CONNECTION_STRING }}\r\n COSMOSDB_DATABASE_NAME: ${{ vars.COSMOSDB_DATABASE_NAME }}\r\n COSMOSDB_CONTAINER_NAME: ${{ vars.COSMOSDB_CONTAINER_NAME }}\r\n\r\n steps:\r\n - name: Checkout repository\r\n uses: actions\/checkout@v4\r\n\r\n - name: Set up .NET\r\n uses: actions\/setup-dotnet@v3\r\n with:\r\n dotnet-version: '8.0.x'\r\n\r\n - name: Export Cosmos DB Emulator Certificate\r\n run: |\r\n sudo apt update && sudo apt install -y openssl\r\n openssl s_client -connect localhost:8081 <\/dev\/null | sed -ne '\/-BEGIN CERTIFICATE-\/,\/-END CERTIFICATE-\/p' > cosmos_emulator.cert\r\n \r\n sudo cp cosmos_emulator.cert \/usr\/local\/share\/ca-certificates\/\r\n sudo update-ca-certificates\r\n\r\n - name: Install dependencies\r\n run: cd dotnet-app && dotnet restore\r\n\r\n - name: Build\r\n run: cd dotnet-app && dotnet build --no-restore\r\n\r\n - name: Run tests\r\n run: cd dotnet-app && dotnet test --no-build --verbosity normal<\/code><\/pre>\nThis job is configured to run on an Ubuntu runner and uses the\u00a0mcr.microsoft.com\/cosmosdb\/linux\/azure-cosmos-emulator:vnext-preview<\/code>\u00a0docker 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\u00a0GitHub Actions hosted runner<\/a>, the\u00a0Run tests<\/strong>\u00a0step can access the emulator using\u00a0localhost:8081<\/code>.<\/p>\nThe\u00a0Export Cosmos DB Emulator Certificate\u00a0step is specific to .NET (as well as Java) applications because at the time of writing, the .NET and Java SDKs do not support\u00a0HTTP<\/code>\u00a0mode in emulator. The\u00a0PROTOCOL<\/code>\u00a0environment variable is set to\u00a0https<\/code>\u00a0in the\u00a0services\u00a0section and this step exports the emulator certificate and adds them to the operating system trusted certificate store.<\/div><\/p>\nTry it out!<\/h2>\n
This\u00a0GitHub repository<\/a>\u00a0provides 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\u00a0x64\u00a0and\u00a0ARM64\u00a0architectures (demonstrated for Linux runner using\u00a0ubuntu<\/code>).<\/p>\nFork the repository<\/h3>\n
Navigate to the GitHub repository, and click the\u00a0Fork<\/strong>\u00a0button at the top-right corner of the repository page to create a copy of the repository under your own GitHub account.<\/p>\nIn your GitHub account, open the repository and make sure to enable workflows in the repository settings.<\/p>\n
![\"A](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2025\/02\/a-screenshot-of-a-computer-description-automatica.png\")
<\/p>\n
Add the Cosmos DB emulator connection string (COSMOSDB_CONNECTION_STRING<\/code>) as\u00a0Repository secret<\/a>\u00a0to the repository. Use the following value:<\/p>\nAccountEndpoint=http:\/\/localhost:8081\/;AccountKey=C2y6yDjf5\/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw\/Jw==<\/code><\/pre>\n![\"A](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2025\/02\/a-screenshot-of-a-computer-description-automatica-1.png\")
<\/p>\n
Add database name (COSMOSDB_DATABASE_NAME<\/code>) and container name (COSMOSDB_CONTAINER_NAME<\/code>) as\u00a0Repository variables<\/a>:<\/p>\n![\"A](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2025\/02\/a-screenshot-of-a-computer-description-automatica-2.png\")
<\/p>\n
Clone the forked repository to your local machine (make sure to use your GitHub username):<\/p>\n
git clone https:\/\/github.com\/<your-username>\/cosmosdb-linux-emulator-github-actions.git\r\n\r\ncd cosmosdb-linux-emulator-github-actions<\/code><\/pre>\nTrigger the workflow<\/h3>\n
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.<\/p>\n
Push your changes to your forked repository on GitHub:<\/p>\n
git add .\r\n\r\ngit commit -m \"Your commit message\"\r\n\r\ngit push origin main<\/code><\/pre>\nAfter pushing the changes, GitHub Actions will automatically run the workflow. Go to the\u00a0Actions<\/strong>\u00a0tab in your repository to see the status and results of the workflows. Review any logs or output to ensure the workflows are running correctly.<\/p>\n![\"A](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2025\/02\/a-screenshot-of-a-computer-description-automatica-3.png\")
<\/p>\n
GitHub Actions runner considerations<\/h2>\n
The\u00a0sample repository<\/a>\u00a0demonstrated\u00a0ubuntu<\/code>\u00a0based runners (for\u00a0x64\u00a0and\u00a0ARM64\u00a0architectures). This should work for\u00a0Windows ARM-based runners<\/a>\u00a0as well. If you are considering Windows\u00a0x64\u00a0runners, note that at the time of writing, GitHub Actions service containers are\u00a0not supported in non-Linux runners<\/a>. But you can work around this by adding\u00a0steps\u00a0to install Docker, and manage its lifecycle including starting and stopping the container.<\/p>\nWrap up<\/h2>\n
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<\/a> and let us know what you think!<\/p>\nLeave a review<\/h2>\n
Tell us about your Azure Cosmos DB experience! Leave a review on PeerSpot and we\u2019ll gift you $50. Get started here<\/a>.<\/p>\nAbout Azure Cosmos DB<\/h2>\n
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.<\/p>\n
Try Azure Cosmos DB for free here.<\/a> To stay in the loop on Azure Cosmos DB updates, follow us on X<\/a>, YouTube<\/a>, and LinkedIn<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"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 […]<\/p>\n","protected":false},"author":181737,"featured_media":9412,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[14],"tags":[539,1933,1783,1738,537,1312],"class_list":["post-9417","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-core-sql-api","tag-net","tag-devops","tag-docker","tag-go","tag-java","tag-python"],"acf":[],"blog_post_summary":"
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 […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/9417","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/users\/181737"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/comments?post=9417"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/9417\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media\/9412"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media?parent=9417"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/categories?post=9417"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/tags?post=9417"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}