Skip to content

GitHub Actions with AWS CDK

GitHub Actions and AWS CDK connect code changes, infrastructure and deployment into a reviewable pipeline – and make the architecture decision visible in the pull request.

≈ 10 min readSoftwareAWSCloud

GitHub Actions with AWS CDK

Two commands carry this setup: cdk diff in the pull request and cdk deploy on main. The first changes nothing and shows everything – new resources, changed permissions, deleted tables. The second changes everything and shows nothing that was not already in the review.

Editorial note (July 2026): The workflow and CDK code show the state of January 2020: Actions v1, Node 12, CDK v1 and permanently stored AWS keys. A setup today calls for current action versions, CDK v2 and short-lived AWS credentials via OpenID Connect in the workflow. The review idea around cdk diff is not affected by this.

This order holds the difference between automation and architecture. Connecting GitHub Actions and AWS CDK takes an hour. What is more interesting is which decision it brings to the table earlier.

Why this combination is more than automation#

GitHub Actions has been generally available for a few weeks, and the obvious reaction is to rebuild the familiar flow with it: build the tests, package the artifact, deploy via script. That works, but it gives away the real lever. Because with AWS CDK, I describe my infrastructure in the same TypeScript repository as my application – Lambda, API Gateway, IAM roles, tables. That turns infrastructure into code that can be reviewed, versioned and tested like any other.

The point I care about only emerges from the interplay. When application code and infrastructure code sit in the same pull request and run through the same pipeline, a change is no longer “new handler” plus “someone clicks a role together in the console later.” It is a single, traceable unit. The code change and its operational consequence sit side by side before anything goes to production. That is the architectural gain – not the clicks saved.

This boundary is often drawn somewhere else. Infrastructure then lives in a wiki, in terminal commands, in the heads of two people. The pipeline deploys the code, but nobody in the review can say which permissions, which resources and which costs a change brings with it. CDK plus GitHub Actions turns this question into an artifact you can discuss.

Approval comes before the workflow#

Before I write YAML, I clarify three concrete points: Who may trigger a deployment? Which changes must be visible in the pull request? And what is the way back if the new stack does not hold? GitHub Actions answers none of these questions. The workflow only enforces the answers. If, for example, a protected environment with approval is missing, cdk deploy on main quickly becomes an automatism that is faster than the control behind it.

cdk diff as a review artifact#

For me, the methodological core of this combination is a single command: cdk diff. It compares the synthesized CloudFormation state with what is actually running in AWS and shows the difference – new resources, changed permissions, deleted tables. If I pull this command into the pull request run, every review gets an honest preview of the operational consequence.

That noticeably changes the quality of a review. A reviewer does not just see that a handler is being added but that this handler brings along a new IAM policy with dynamodb:*. This line in the diff is the moment a bad decision stands out – before the merge, not in the next security audit. I thereby move an error from “expensive and late” to “cheap and early,” and that is the concrete effect this is about.

The diff also uncovers a class of problems that otherwise stays invisible: drift. If someone changes a resource by hand in the console, the real state deviates from the code. Without a diff, nobody notices until a deployment silently overwrites the manual change and something breaks that “was still working yesterday.” With the diff in the pull request, this deviation becomes a visible signal – and an opportunity to ask the real question: why was someone working in the console, and how do I bring this change back into the code where it belongs? The diff is thus not just a review tool but a quiet way of disciplining the whole team toward “the code is the truth.”

A small stack#

The basis is a deliberately small stack – a Lambda behind an API Gateway. It is not meant to simulate a complete application but to show the boundary.

import * as cdk from "@aws-cdk/core";
import * as lambda from "@aws-cdk/aws-lambda";
import * as apigw from "@aws-cdk/aws-apigateway";

export class ApiStack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const handler = new lambda.Function(this, "ApiHandler", {
      runtime: lambda.Runtime.NODEJS_12_X,
      handler: "index.handler",
      code: lambda.Code.fromAsset("dist/api"),
      timeout: cdk.Duration.seconds(10)
    });

    new apigw.LambdaRestApi(this, "Api", { handler });
  }
}

What is interesting is less what is here than what is not here. LambdaRestApi is a construct that creates an API, an integration and the matching execution role in the background. That is the value of a good abstraction: it reduces repetition and encapsulates sensible defaults. And that is also its risk – it must not hide which resources, permissions and costs actually come about. cdk diff is exactly the control that makes the hidden visible again.

A good example has few features and one point you can argue about after five minutes. The timeout is such a point: ten seconds is an operational decision, not a detail, and it belongs in the code, not in a verbal agreement.

The pipeline#

The pipeline has two jobs that I keep cleanly separate. In the pull request, it shows the diff without changing anything. On main, it deploys. This separation is not cosmetic – it ensures that the preview has no consequences and the deployment has a clear trigger.

name: deploy

on:
  push:
    branches: [main]
  pull_request:

jobs:
  diff:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1
        with:
          node-version: "12"
      - run: npm ci
      - run: npm run build
      - run: npx cdk diff
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_DEFAULT_REGION: eu-central-1

  deploy:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1
        with:
          node-version: "12"
      - run: npm ci
      - run: npm run build
      - run: npx cdk deploy --require-approval never
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_DEFAULT_REGION: eu-central-1

The credentials are stored as GitHub secrets in the repository and passed to the CDK CLI via environment variables. That is the pragmatic route I take today – and at the same time the place with the greatest responsibility; more on that in a moment.

The flow as a sketch:

flowchart LR
  PR[Pull request] --> Diff[cdk diff<br/>visible in review]
  Diff --> Merge[Merge to main]
  Merge --> Build[Build + synth]
  Build --> Deploy[cdk deploy]
  Deploy --> CFN[CloudFormation<br/>Change Set]
  CFN --> Observe[Logs + metrics]

An environment you can reproduce#

As soon as the first stack is running, the question of staging and production comes up. And this is where it shows why infrastructure as code is more than a more convenient deployment. Because my stack is a TypeScript class, I can parameterize it and instantiate it twice – the same definition, different names, different accounts. Staging is then, by construction, an exact copy of production, not an environment that slowly drifts apart over months until nobody knows anymore which difference was intended and which was chance.

This is one of the methodological consequences I value most. The classic break between “works on my machine” and “works in production” almost always comes from environment differences that nobody documented. When the environment itself is versioned, this break does not disappear completely, but it becomes a question I can answer in the repository instead of a puzzle I solve under time pressure in the production system. That is exactly why, for me, CDK belongs to the topic of reproducibility. The deployment steps saved are just the visible side effect.

Permissions that do not grow with every convenience#

The most tempting shortcut is a deploy identity with AdministratorAccess. It always works, it never explains an error, and it is the reason a compromised repository becomes a compromised account. The trade-off is real: a narrowly cut role means that a deployment occasionally fails on a missing permission and I have to tighten things up. But this failure is cheap and instructive, while silent full access only gets expensive once.

Serverless moves operational work; it does not remove it. Permissions, logs, cold starts, timeouts, costs and the ability to roll back still have to be designed explicitly. The difference is that with CDK I design them in the same review in which I write the handler – instead of postponing them to “we’ll do it later.” In practice, “later” is the name for “never.”

Rollback and the happy-path fallacy#

That leaves overrating the happy path. Many pipelines look clean as long as every deployment succeeds. It gets interesting with partial failures: one resource is created, the next one fails, and the stack is stuck halfway.

What helps here is that CDK builds on CloudFormation. A failed deployment rolls back to the last consistent state, and this behavior is part of the platform, not of my script. That is a strong reason to stay with CDK instead of stringing individual resources together with imperative CLI calls: I get a defined transaction boundary for free. Still, I have to know it. A deployment that migrates data is not automatically reversible just because the stack is – the question of idempotency and repeatability remains mine.

What changes measurably as a result#

When these parts work together, the work changes noticeably, and in a direction I can explain to a technical decision-maker. The cycle from “idea” to “running in production” gets shorter because there is no longer a manual handover step between code and infrastructure. Friction in the team drops because nobody holds deployment knowledge as personal gatekeeping knowledge anymore – it lives in the repository. And quality rises because cdk diff moves an error to where it is cheap: into the pull request.

Concretely, it looks like this: in a team without this setup, an infrastructure change takes as long as the available person with AWS access needs – plus the time until someone notices that the change turned out differently in staging and production. With the pipeline, the same change is a pull request that two colleagues can read without having console access themselves. The “one person with permissions” bottleneck disappears, and with it the silent queue that nobody ever sees on a board. That is developer productivity in the literal sense: not typing faster, but fewer handovers, fewer follow-up questions, fewer states in which someone is waiting for someone else.

That is the arc from mechanics to effect. GitHub Actions and CDK are interchangeable tools. The reusable decision behind them – treating infrastructure as a reviewable part of every change – is not.

What I check in the review#

When reviewing this setup, I ask three questions. Does the pull request show the operational consequence, that is, the diff, or only the application code? Is the deploy identity cut so narrowly that I can explain a permission error instead of configuring it away? And is it clear what happens when a deployment has run halfway?

If one of these questions remains open, the pipeline is still missing something – a visible diff, a sharper role or a clarified rollback path. A construct should reduce repetition and encapsulate good defaults, but never obscure which resources, permissions and costs come about. It is exactly at this edge between convenient abstraction and honest visibility that it is decided whether the combination holds.

Further reading#

The sources help you cross-check platform behavior. The actual statement remains the architecture decision in the concrete example.

Closing#

Bringing GitHub Actions and CDK together is done quickly. The return lies in the boundary between application and platform moving into the pull request. That is where the benefit arises for developers, architects and technical decision-makers. It hinges on a reusable decision: taking infrastructure as seriously as the code that runs on it. The tool name is interchangeable.

Revised and translated from German with the help of AI.