Skip to Content
Cloud Engineering Academy
9. DevOps & CI/CD

Lab 9.1: a CI workflow with Testcontainers and LocalStack

Run the Accounts API test suite locally in Docker, read the ci.yml workflow job by job, add a LocalStack-backed integration test with Testcontainers, and download JUnit results as pipeline evidence, all without an AWS account or any AWS credentials.

intermediateā± 1 h 15 min🟢 FreeDOP-C02DVA-C03

Assumes: .NET 10 LTS Ā· xUnit v3 4.0.3 on Microsoft.Testing.Platform Ā· Testcontainers.LocalStack 4.17.0 Ā· GitHub Actions (actions/checkout v7.0.1, actions/setup-dotnet v6.1.0, actions/upload-artifact v7.0.2) Ā· Docker Ā· labs/m09-delivery-pipeline. Verified against official sources on 2026-11-18.

Learning objectives

By the end of this lab you can:

  • Run the whole test suite of the Module 9 lab project with Docker only, and explain why 74 passed, 1 skipped is the expected result.
  • Read ci.yml and say, for every job, what it proves and why it needs no AWS credentials.
  • Run the LocalStack integration test with Testcontainers, and handle the LocalStack auth-token change without putting a token in the repository.
  • Produce JUnit test results as a pipeline artefact and explain why an auditor cares about a retained test report.
  • Break a test on purpose and watch the pipeline gate the pull request.

Prerequisites

  • Git and GitHub for regulated teams, for branch protection and required status checks.
  • Automated testing strategy, for the test pyramid this lab applies.
  • Docker Desktop running. The .NET SDK is optional: every command below also works inside the official SDK image.
  • A GitHub repository of your own if you want to see the workflow run (optional; the local steps stand alone).

Scenario

Harbourline Bank's platform team wants every pull request to the Accounts API to answer one question before a human reviews it: "does this change still build, pass its tests and produce a container that starts?" Pull requests can come from forks and contributors you do not fully trust, so the answer must be produced by a workflow that holds no cloud credentials at all. This lab is that workflow.

Architecture

What 'no credentials' means here

The workflow sets permissions: contents read, so the automatic GITHUB_TOKEN can only read the repository. It never requests an OIDC token (id-token: write is absent), so even a malicious pull request cannot obtain AWS access from it. LocalStack accepts the fake credentials test / test, and the lab code says so in a comment: real keys never belong in a test.

The test suite at a glance

The solution DeliveryPipeline.slnx holds two test projects, both xUnit v3 running on Microsoft.Testing.Platform (opted in through global.json), so each test project is a small executable.

Test classKindWhat it provesNeeds Docker?
IdentifierTestsUnitAccount and customer ID formats (ACC- plus ten digits, CUS- plus eight)No
ApiIntegrationTestsIn-process integrationWhole ASP.NET Core pipeline through WebApplicationFactory: health checks, /version, the forced-unready drillNo
AccountContractTestsContractThe JSON shape clients depend on does not change by accidentNo
TrustPolicyTestsUnit, data drivenWhich GitHub tokens can assume which IAM roles (Lab 9.2)No
ImageAndGateTestsUnitImage tag rules, digest pinning, canary health gate, release policyNo
EvidenceStoreTestsUnit with a substituteS3 write uses KMS, no-overwrite and a hash, with IAmazonS3 replaced by NSubstituteNo
EvidenceStoreLocalStackTestsIntegrationReal S3 API behaviour against LocalStack, including refusing an overwriteYes

Analogy: unit tests are checking each cheque-processing rule with a calculator; the in-process integration tests are running a whole payment through a mock branch; the LocalStack test is a dress rehearsal in a rented hall that looks like the real bank, with none of the real money.

Microsoft / Azure comparison

You know (Microsoft/Azure)In this labWhat's different
WebApplicationFactory<Program> in an xUnit projectSame, used by ApiIntegrationTestsUnchanged: it is the cheapest, fastest integration test you have
Azurite or the Cosmos DB emulator for Azure Storage testsLocalStack for S3 through TestcontainersLocalStack emulates many AWS APIs; coverage and fidelity vary by service
Azure Pipelines PublishTestResults task--report-junit plus actions/upload-artifactJUnit XML is the common format; GitHub shows the artefact, you retain it
Pipeline run on a Microsoft-hosted agentGitHub-hosted ubuntu-latest runnerDocker is preinstalled on the Ubuntu runner, which is why Testcontainers works unchanged

Step-by-step implementation

Get the lab files

Work from a copy so your changes never touch the curriculum folder. In Git Bash or PowerShell:

cp -r labs/m09-delivery-pipeline ~/m09-delivery-pipeline
cd ~/m09-delivery-pipeline
ls

You should see DeliveryPipeline.slnx, Dockerfile, src/, tests/, policies/, samples/, .github/ and infra/. GitHub only runs workflows found in .github/workflows at the root of a repository, so for the GitHub part of this lab, initialise a new repository from this folder's contents.

Run every test that needs no Docker daemon, inside Docker

docker run --rm -v "${PWD}:/src" -w /src \
  mcr.microsoft.com/dotnet/sdk:10.0 \
  dotnet test --solution DeliveryPipeline.slnx

In Git Bash on Windows prefix the command with MSYS_NO_PATHCONV=1 so the volume path is not rewritten. The last lines of a healthy run read:

skipped Harbourline.Delivery.Tests.EvidenceStoreLocalStackTests.Round_trips_evidence_through_s3_and_refuses_overwrite
  Set RUN_LOCALSTACK_TESTS=1 (and have Docker running) to run LocalStack integration tests.

Test run summary: Passed!
  total: 75
  failed: 0
  succeeded: 74
  skipped: 1

The skip is deliberate. A test that needs a container runtime fails confusingly on a machine without Docker, so the lab gates it behind RUN_LOCALSTACK_TESTS=1 using Assert.SkipUnless, and it appears in the report as skipped, not silently missing.

Read the workflow top to bottom

Open .github/workflows/ci.yml and find these decisions. Each one is a security or audit control rather than decoration.

Line or blockWhy it is there
on: pull_request and push to mainEvery proposed change is tested before merge; main is tested again after merge
permissions: contents: read at the topThe GITHUB_TOKEN is read-only unless a job asks for more
concurrency with cancel-in-progress: trueA new push to the same branch cancels the stale run and saves minutes
uses: actions/checkout@3d3c42e… # v7.0.1Third-party actions are pinned to a full commit SHA; the comment records the tag for humans
persist-credentials: falseThe checkout does not leave a token in .git/config for later steps to read
global-json-file: global.jsonThe SDK version comes from the repository, so a laptop and the runner agree
timeout-minutes on every jobA hung test cannot burn the whole monthly allowance
if: github.event_name == 'push' on localstack-integrationThe only job that needs a secret (the LocalStack token) never runs for pull requests, including those from forks

Follow the build-and-test job

The job restores, builds and tests in three separate steps, so the log shows which stage failed:

- name: Restore (NuGet Audit fails on high/critical advisories)
  run: dotnet restore DeliveryPipeline.slnx

- name: Build (warnings are errors)
  run: dotnet build DeliveryPipeline.slnx --no-restore -c Release

- name: Test (JUnit reports for the run summary and evidence pack)
  run: >
    dotnet test --solution DeliveryPipeline.slnx --no-build -c Release
    --report-junit --results-directory ${{ github.workspace }}/artifacts/test-results

Directory.Build.props turns on NuGet Audit for direct and transitive packages and treats high (NU1903) and critical (NU1904) advisories as errors, so a vulnerable dependency fails the restore step before any test runs. --report-junit is an option of the xUnit v3 / Microsoft.Testing.Platform extension; the files land in artifacts/test-results and the next step uploads them with if: always(), so a failed run still keeps its report.

Run the container job locally

The container-build job builds the image without pushing it, starts it, and probes it:

docker build --build-arg VERSION=0.0.0-ci.1 --build-arg GIT_SHA=$(git rev-parse HEAD) -t hl-m09-accounts-api:pr-1 .
docker run -d --name api -p 8080:8080 hl-m09-accounts-api:pr-1
curl -fsS http://localhost:8080/health/ready
curl -fsS http://localhost:8080/version
docker rm -f api

/version returns the version and commit that were stamped into the build, for example {"version":"0.0.0-ci.1","commit":"<sha>","environment":"Production","releaseId":null}. The final image is a chiseled, non-root ASP.NET runtime without a shell, which is why the smoke test uses curl from the runner rather than a HEALTHCHECK inside the container.

Run the LocalStack integration test

The test builds a LocalStack container with Testcontainers.LocalStack 4.17.0, creates a bucket, saves a release-evidence record, reads it back and proves that a second save to the same key is refused (S3 conditional write with If-None-Match: *).

LocalStack now needs an auth token for newer images

LocalStack images published after 2026-03-23 require an auth token; a free Hobby plan exists for non-commercial use ⚠ VERIFY the current plan terms before relying on them. The lab supports two routes: set LOCALSTACK_AUTH_TOKEN from your own account, or pin an older tag with LOCALSTACK_IMAGE=localstack/localstack:4.14 ⚠ VERIFY that pre-change tags still start without a token. Never commit the token. In GitHub it belongs in a repository or environment secret.

Testcontainers needs to reach the Docker daemon. From a normal developer shell, run:

export RUN_LOCALSTACK_TESTS=1
export LOCALSTACK_AUTH_TOKEN=<your token>      # or: export LOCALSTACK_IMAGE=localstack/localstack:4.14
dotnet test --solution DeliveryPipeline.slnx

If you only have Docker and no SDK on the host, give the test container access to the Docker socket (Linux and macOS style shown; Docker Desktop on Windows exposes the socket through the Linux VM):

docker run --rm -v "${PWD}:/src" -v /var/run/docker.sock:/var/run/docker.sock -w /src \
  -e RUN_LOCALSTACK_TESTS=1 -e LOCALSTACK_AUTH_TOKEN \
  mcr.microsoft.com/dotnet/sdk:10.0 dotnet test --solution DeliveryPipeline.slnx

Mounting the Docker socket gives the container control of the host's Docker, so do it only for code you trust. This is a learning shortcut, covered below. With the test enabled the summary becomes succeeded: 75, skipped: 0 ⚠ VERIFY on your machine, since image pulls and networking differ.

Find the artefacts

In GitHub: Actions → the run → Summary → Artifacts → test-results. The retention is 30 days (retention-days: 30). The XML contains one entry per test with its duration and outcome. For the release evidence pack in the project page you will pull the pass, fail and skip counts from it.

Code explained

The LocalStack test is short enough to read in full. Open tests/Harbourline.Delivery.Tests/EvidenceStoreTests.cs.

  1. Assert.SkipUnless(Environment.GetEnvironmentVariable("RUN_LOCALSTACK_TESTS") == "1", …) turns an environment variable into a conditional skip and prints the reason. This is xUnit v3 behaviour, so nothing needs to be installed.
  2. new LocalStackBuilder(image) creates a container definition; the image comes from LOCALSTACK_IMAGE or defaults to localstack/localstack:4.14.
  3. builder.WithEnvironment("LOCALSTACK_AUTH_TOKEN", token) passes the token only when set, so the same test works with or without one.
  4. await using var localstack = builder.Build(); await localstack.StartAsync(ct); starts the container and guarantees it is removed when the test ends, even on failure.
  5. new AmazonS3Client(new BasicAWSCredentials("test", "test"), new AmazonS3Config { ServiceURL = localstack.GetConnectionString(), ForcePathStyle = true, … }) points the real AWS SDK for .NET client at the emulator. ForcePathStyle is needed because the emulator is addressed as host:port/bucket, not bucket.host.
  6. EvidenceStore.SaveAsync is the production code under test. The unit-level sibling test uses Substitute.For<IAmazonS3>() to assert the request it builds: KMS encryption, IfNoneMatch = "*" and a sha256 metadata entry.

Where each kind of test belongs

Use a substitute for the SDK client when you want to assert what your code asks AWS to do. Use LocalStack when you want to find out whether the AWS API accepts it. Neither proves IAM permissions or real service limits; those need a sandbox account test, gated behind an environment variable such as RUN_AWS_TESTS=1.

Security considerations

⚠ Learning shortcut — not for production

Mounting /var/run/docker.sock into a build container, and running Testcontainers on a shared runner, let that code control the host's container engine, which is close to root on the machine. GitHub-hosted runners are single-use virtual machines, so the risk is bounded there. On self-hosted runners, use rootless Docker or an ephemeral runner per job, and never run untrusted pull-request code on a long-lived self-hosted runner.

  • Pull-request code is untrusted. The ci workflow uses the pull_request trigger, which gives fork runs a read-only token and no secrets. The dangerous triggers are pull_request_target and workflow_run, which run in the base repository's context; do not check out and execute fork code from them. See Secrets in CI/CD.
  • Pin actions to commit SHAs. A tag such as v7 can be moved by whoever controls the action. Dependabot (.github/dependabot.yml) raises reviewed pull requests to update the pinned SHAs.
  • Test credentials are fake and obvious. test / test is accepted by LocalStack only. Real credentials in a test are a leak waiting to happen, and the Gitleaks job in Lab 9.3 would flag them.
  • Test data is fictional. The fixtures use ACC- and CUS- identifiers and invented people; never copy production data into a test.

Common mistakes

  • Treating "skipped" as "passed". A green run with 0 tests is not evidence. The release policy in the project page rejects a release with Tests.Passed == 0.
  • Putting the LocalStack token in ci.yml. Use a secret, and expect the secret to be empty on fork pull requests.
  • Testing against a real AWS account in CI "just this once". This needs an OIDC role, which is a deliberate step covered in GitHub Actions with OIDC.
  • Running tests with --no-build before building. The workflow builds first in a separate step; skipping that gives a confusing "no tests found" result.

Troubleshooting

SymptomLikely causeFix
Cannot connect to the Docker daemon in the LocalStack testDocker is not running, or the socket is not mounted when tests run inside a containerStart Docker Desktop; mount the socket as shown, or run dotnet test on the host
LocalStack container starts then exits, log mentions an auth tokenImage newer than the token change and no token setSet LOCALSTACK_AUTH_TOKEN, or pin LOCALSTACK_IMAGE to an older tag
NU1903 or NU1904 during restoreA package has a high or critical advisoryUpdate the package; record an exception only when no fixed version exists
MSBuild MSB3026 copy retries, then GenerateDepsFile failsTwo test runs share the same bin/ folder, for example two containers on one mountRun one at a time and delete bin/ and obj/ afterwards
Passes locally, fails on the runnerDifferent SDK, or a path or case-sensitivity issue on LinuxUse global.json, run the SDK container locally, check file-name case
No test-results artefactThe --results-directory path is wrong, or the job was cancelled before uploadConfirm the path in the step log; keep if: always() on the upload

Cost and cleanup

Cost: free. There is no AWS account involved. GitHub-hosted runners are free for public repositories, and private repositories have a monthly allowance of minutes ⚠ VERIFY the current allowance on GitHub's pricing page. LocalStack's free plan is for non-commercial use ⚠ VERIFY.

# Remove test images and any stray LocalStack containers
docker rm -f api 2>/dev/null
docker ps -a --filter "ancestor=localstack/localstack" -q | xargs -r docker rm -f
docker image rm hl-m09-accounts-api:pr-1 2>/dev/null

# Remove build output the SDK container left in the mounted folder
find . -type d \( -name bin -o -name obj \) -prune -exec rm -rf {} +

Exercises

  • 🟢 Guided: run the whole suite in Docker. Then change the expected string in Key_is_partitioned_by_service_and_year (for example 2027), run again, and read the failure message. Revert the change.
  • 🟔 Challenge: add a new unit test for Identifiers.IsAccountId with a tenth digit replaced by a letter, then add a job to ci.yml that runs only the Harbourline.Accounts.Api.Tests project, so pull requests get a faster first signal.
  • šŸ”“ Live problem: after the LocalStack token change, the main-branch job started failing every morning with "image requires auth token", and the team says "just turn the test off". Propose and justify an alternative that keeps the S3 behaviour tested. Consider pinning, caching the image, a nightly job, and what the test actually needs to prove.

Assignment

Fork the lab into your own repository. Make the build-and-test, container-build and iam-policy-lint jobs required status checks on main with a ruleset, open a pull request that breaks a test, and capture a screenshot or log excerpt showing the merge is blocked. Add it to your portfolio README with one paragraph on why the workflow needs no cloud credentials.

Solutions

Knowledge check

Interview questions

  • Why does a pull-request workflow need no AWS credentials? Because it only proves the code builds and passes tests; deployment is a separate, approved, credentialed stage on a protected branch or environment. Keeping PR jobs credential-free removes the most dangerous attack path.
  • What is the difference between mocking the AWS SDK and using LocalStack? Mocks check the calls your code makes. LocalStack checks that a real API implementation accepts them, with more setup, slower runs and imperfect fidelity.
  • How would you keep a flaky container-based test from blocking releases? Quarantine with an explicit skip and a ticket, run it on a schedule, and keep a fast deterministic test in the required checks. Never delete it silently.

Certification practice

Completion checklist

  • I ran the test suite in Docker and saw 74 passed, 1 skipped
  • I can explain every permissions and pinning choice in ci.yml
  • I ran the LocalStack test, or documented why I could not and which route (token or pinned image) I would use
  • I found the JUnit artefact and its retention period
  • I deleted test images, containers and bin/ and obj/ folders

Key takeaways

  • A pull-request pipeline proves quality without cloud credentials; keep it that way.
  • Test at the cheapest level that can catch the bug: unit, in-process integration, then emulator.
  • Gate Docker-dependent tests behind an explicit switch and make skips visible.
  • Retained, structured test results are the first piece of release evidence.
  • Pin dependencies and actions; never commit tokens, even test ones.

Further reading

Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.

On this page