How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/matt-riley/agent-skills --skill aws-lambda-go-deploymentBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
AWS Lambda Go deployment
Use this skill when a Go Lambda fails because the binary, runtime, package layout, or event wiring is wrong and you need the smallest deployment-focused fix before widening into SAM, IAM, or CI triage.
Use this skill when
- A Go AWS Lambda fails to deploy, package, or start correctly.
sam buildor a manual zip step is producing the wrong binary layout for a Go function.- The function is missing
bootstrap, uses the wrong handler name, or was built for macOS instead of Linux. - You need to check Lambda Function URL or API Gateway wiring after confirming the Go binary should boot.
- CloudWatch Logs need inspection to separate init/runtime failures from application-code failures.
Do not use this skill when
- The main problem is SAM template YAML, CloudFormation stack behavior, or IAM role wiring.
- The failure is
AccessDeniedonsts:AssumeRoleorsts:AssumeRoleWithWebIdentity. - The core issue is a plain Go compile or test failure before Lambda packaging begins.
- The primary failure is a GitHub Actions workflow problem rather than the Lambda deployment path itself.
Routing boundary
| Situation | Use this skill? | Route instead |
|---|---|---|
| Go Lambda packaging, runtime, bootstrap, or handler problems | Yes | - |
| SAM template YAML, CloudFormation stack rollback, or IAM resource wiring | No | `sam-cloudformation` |
| Deploy workflow fails on AssumeRole or OIDC auth | No | `sam-cloudformation` |
| Go code does not compile before packaging | No | `testing-workflows` |
| CI workflow structure or runner behavior is failing | No | `github-actions-failure-triage` |
Inputs to gather
Required before editing
- Target Lambda architecture (
amd64orarm64) and whether the function runs on Graviton. - Build path:
sam build, Makefile, or manualgo buildplus zip. - Runtime and handler settings from the SAM template or deployment config.
- The exact error from Lambda, SAM, or CloudWatch Logs.
Helpful if present
sam buildoutput or Docker build logs.- The built artifact layout (
bootstrap, handler path, zip contents). - Function URL or API Gateway event configuration.
- Recent CloudWatch log lines around
INIT_STARTandSTART.
Only investigate if encountered
- Cross-account deploy wiring.
- Downstream API Gateway integration responses after the function starts successfully.
- Provisioned concurrency or alias-specific rollout details.
First move
- Classify the failure as build-time, package-layout, runtime-startup, or event-wiring.
- Confirm the target runtime, architecture, and executable name before changing code.
- Prefer
sam build --use-containeror an equivalent Linux build path before trusting a local macOS binary.
Workflow
- Confirm the Lambda runtime contract first: for Go functions prefer
provided.al2orprovided.al2023, not deprecatedgo1.x. - Build for the real Lambda target: use
sam build --use-containerfor reproducible Linux builds, or manually cross-compile withGOOS=linuxandGOARCH=amd64(orarm64on Graviton). - Verify the artifact layout matches the runtime expectation:
- zipped custom-runtime binaries should be named
bootstrap - SAM
Handlervalues must match the deployed executable path when that path is used instead ofbootstrap
- Inspect the built zip or
.aws-samoutput before redeploying so you know whether the executable, permissions, and path are correct. - If deployment succeeds but invocation fails, read CloudWatch Logs and look for
INIT_STARTandSTARTbefore assuming an application-code bug. - If the binary boots, then check Function URL or API Gateway wiring, event payload shape, and template event definitions.
- Route away immediately when the real blocker is SAM stack configuration, IAM OIDC auth, CI orchestration, or a plain Go build failure.
Outputs
- A clear diagnosis of whether the failure is packaging, runtime selection, artifact layout, or event wiring.
- The corrected build/deploy assumptions for Linux architecture, executable naming, and runtime choice.
- A clean handoff to
sam-cloudformation,testing-workflows, orgithub-actions-failure-triagewhen this skill is not the right owner.
Guardrails
- Never trust a macOS-built Go binary to run in Lambda; cross-compile for Linux or build in a SAM container.
- Never keep
go1.xas the target runtime for new or repaired Go Lambda deployments. - Never assume a code bug before checking CloudWatch init/start logs for startup evidence.
- Do not stretch this skill into SAM stack repair or IAM trust-policy debugging once those are the primary blocker.
Validation
- Confirm the runtime is
provided.al2orprovided.al2023and the target architecture matches the deployed function. - Confirm the deployment artifact contains the expected executable name (
bootstrapor the configured handler path). - Re-run the narrowest available build or packaging command and verify the artifact layout before redeploying.
- If the function is deployed, inspect CloudWatch logs for
INIT_STARTandSTARTto confirm whether the runtime got far enough to execute code. - Smoke test:
- should trigger: "Our Go Lambda was built on macOS and now fails in AWS with an exec-format or missing-bootstrap style startup error."
- should not trigger: "The deploy job fails before deployment because GitHub Actions gets AccessDenied on AssumeRoleWithWebIdentity." (→
sam-cloudformation)
Examples
- "Package this Go Lambda for SAM so it runs on Lambda instead of failing at startup with a missing
bootstrap." - "We switched a Go function to Lambda arm64 and now the binary will not start; check the runtime, GOARCH, and zip layout."
- "This Go Lambda deploys, but the Function URL returns errors; verify the binary boots before checking the event wiring."
Reference files
- `references/packaging-checklist.md` - quick checks for Linux cross-compilation, runtime choice, artifact naming, and route-away cues.