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.
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 skippedis the expected result. - Read
ci.ymland 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 class | Kind | What it proves | Needs Docker? |
|---|---|---|---|
IdentifierTests | Unit | Account and customer ID formats (ACC- plus ten digits, CUS- plus eight) | No |
ApiIntegrationTests | In-process integration | Whole ASP.NET Core pipeline through WebApplicationFactory: health checks, /version, the forced-unready drill | No |
AccountContractTests | Contract | The JSON shape clients depend on does not change by accident | No |
TrustPolicyTests | Unit, data driven | Which GitHub tokens can assume which IAM roles (Lab 9.2) | No |
ImageAndGateTests | Unit | Image tag rules, digest pinning, canary health gate, release policy | No |
EvidenceStoreTests | Unit with a substitute | S3 write uses KMS, no-overwrite and a hash, with IAmazonS3 replaced by NSubstitute | No |
EvidenceStoreLocalStackTests | Integration | Real S3 API behaviour against LocalStack, including refusing an overwrite | Yes |
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 lab | What's different |
|---|---|---|
WebApplicationFactory<Program> in an xUnit project | Same, used by ApiIntegrationTests | Unchanged: it is the cheapest, fastest integration test you have |
| Azurite or the Cosmos DB emulator for Azure Storage tests | LocalStack for S3 through Testcontainers | LocalStack emulates many AWS APIs; coverage and fidelity vary by service |
Azure Pipelines PublishTestResults task | --report-junit plus actions/upload-artifact | JUnit XML is the common format; GitHub shows the artefact, you retain it |
| Pipeline run on a Microsoft-hosted agent | GitHub-hosted ubuntu-latest runner | Docker 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
lsYou 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.slnxIn 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: 1The 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 block | Why it is there |
|---|---|
on: pull_request and push to main | Every proposed change is tested before merge; main is tested again after merge |
permissions: contents: read at the top | The GITHUB_TOKEN is read-only unless a job asks for more |
concurrency with cancel-in-progress: true | A new push to the same branch cancels the stale run and saves minutes |
uses: actions/checkout@3d3c42e⦠# v7.0.1 | Third-party actions are pinned to a full commit SHA; the comment records the tag for humans |
persist-credentials: false | The checkout does not leave a token in .git/config for later steps to read |
global-json-file: global.json | The SDK version comes from the repository, so a laptop and the runner agree |
timeout-minutes on every job | A hung test cannot burn the whole monthly allowance |
if: github.event_name == 'push' on localstack-integration | The 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-resultsDirectory.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.slnxIf 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.slnxMounting 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.
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.new LocalStackBuilder(image)creates a container definition; the image comes fromLOCALSTACK_IMAGEor defaults tolocalstack/localstack:4.14.builder.WithEnvironment("LOCALSTACK_AUTH_TOKEN", token)passes the token only when set, so the same test works with or without one.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.new AmazonS3Client(new BasicAWSCredentials("test", "test"), new AmazonS3Config { ServiceURL = localstack.GetConnectionString(), ForcePathStyle = true, ⦠})points the real AWS SDK for .NET client at the emulator.ForcePathStyleis needed because the emulator is addressed ashost:port/bucket, notbucket.host.EvidenceStore.SaveAsyncis the production code under test. The unit-level sibling test usesSubstitute.For<IAmazonS3>()to assert the request it builds: KMS encryption,IfNoneMatch = "*"and asha256metadata 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
ciworkflow uses thepull_requesttrigger, which gives fork runs a read-only token and no secrets. The dangerous triggers arepull_request_targetandworkflow_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
v7can 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/testis 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-andCUS-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-buildbefore building. The workflow builds first in a separate step; skipping that gives a confusing "no tests found" result.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Cannot connect to the Docker daemon in the LocalStack test | Docker is not running, or the socket is not mounted when tests run inside a container | Start Docker Desktop; mount the socket as shown, or run dotnet test on the host |
| LocalStack container starts then exits, log mentions an auth token | Image newer than the token change and no token set | Set LOCALSTACK_AUTH_TOKEN, or pin LOCALSTACK_IMAGE to an older tag |
NU1903 or NU1904 during restore | A package has a high or critical advisory | Update the package; record an exception only when no fixed version exists |
MSBuild MSB3026 copy retries, then GenerateDepsFile fails | Two test runs share the same bin/ folder, for example two containers on one mount | Run one at a time and delete bin/ and obj/ afterwards |
| Passes locally, fails on the runner | Different SDK, or a path or case-sensitivity issue on Linux | Use global.json, run the SDK container locally, check file-name case |
No test-results artefact | The --results-directory path is wrong, or the job was cancelled before upload | Confirm 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 example2027), run again, and read the failure message. Revert the change. - š” Challenge: add a new unit test for
Identifiers.IsAccountIdwith a tenth digit replaced by a letter, then add a job toci.ymlthat runs only theHarbourline.Accounts.Api.Testsproject, 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
Expected failure text names the expected and actual key, for example Assert.Equal() Failure with the two strings, and the summary shows failed: 1, succeeded: 73, skipped: 1. Exit code is 1 and the run summary says Failed!. The point: a test that fails with a clear message is a control. Reverting the change restores succeeded: 74.
Add to ci.yml, under jobs:, a job with the same actions/checkout and actions/setup-dotnet steps (keep the pinned SHAs) and a run step dotnet test --project tests/Harbourline.Accounts.Api.Tests (with xUnit v3 on Microsoft.Testing.Platform the project is passed with --project; check dotnet test --help on your SDK ā VERIFY). Give the job timeout-minutes: 10. Keep permissions read-only. The advantage is speed and an unambiguous failure location; the disadvantage is duplicated setup, so a reusable workflow is the next step.
Knowledge check
Answer: The LocalStack token is a secret, and pull requests from forks must never receive secrets. Restricting the job to push events keeps the secret out of untrusted runs. Running it on every PR from the same repository would be safe for secrets but costs minutes; teams often accept the trade-off differently.
Answer: No. The skipped test is the LocalStack test gated by RUN_LOCALSTACK_TESTS. It is reported as skipped on purpose. It becomes a failure of process only if the pipeline was supposed to run it and silently did not.
Answer: Tags and branches are mutable. A compromised or malicious maintainer can retarget a tag to new code that then runs in your workflow, possibly with secrets. A full SHA is immutable. The tag in a trailing comment keeps it readable, and Dependabot proposes updates.
Answer: Nothing about IAM. LocalStack accepts any credentials, so the tests cannot verify permissions. They verify that your code builds valid requests and handles responses; permission problems appear only against real AWS.
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
A team wants pull requests from external contributors to run unit tests but must not expose AWS credentials to that code. Which approach is correct? A. Trigger on pull_request with read-only GITHUB_TOKEN and no AWS role. B. Trigger on pull_request_target and check out the fork's head. C. Store an IAM access key as a repository secret. D. Use a self-hosted runner with an instance profile.
Answer: A. B runs untrusted code in the base repository's trusted context with secrets available. C stores a long-lived key that fork code could try to exfiltrate in other workflows. D gives untrusted code the runner's AWS identity.
A CodeBuild project must publish unit test results so they appear in the console and can be retained. What belongs in the buildspec? A. An artifacts section only. B. A reports section with a report group and file format such as JUnit XML. C. An env section. D. A cache section.
Answer: B. The reports section publishes test results to a report group. artifacts stores files but does not give a test-report view, env sets variables, and cache speeds later builds.
Completion checklist
- I ran the test suite in Docker and saw
74 passed, 1 skipped - I can explain every
permissionsand pinning choice inci.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/andobj/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
- Testcontainers for .NET ā modules, including LocalStack
- LocalStack documentation ā images, auth tokens and supported services
- Integration tests in ASP.NET Core (Microsoft Learn)
- Next: the module project and Lab 9.2: OIDC deploy role
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.
Automated testing strategy for pipelines: unit, integration, contract, end-to-end and load
Decide which tests run at which pipeline stage, write fast unit tests, in-process integration tests, Testcontainers tests against PostgreSQL and LocalStack, a consumer contract test, a post-deploy smoke test and a k6 load test, and keep the whole suite trustworthy and quick.
ECS deployment strategies: rolling, blue/green, linear and canary
Choose and configure the right Amazon ECS deployment strategy for a .NET API, wire alarm-based and circuit-breaker rollback, use lifecycle hooks as release gates, and rehearse a failed release on purpose.