> ## Documentation Index
> Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Lambda deployment

> How Go queue workers deploy from GitHub Actions and how concurrency works.

## Overview

Production Go Lambdas under `apps/*-lambda` ship through the [Lambda Deploy](https://github.com/hyperlocalise/hyperlocalise/blob/main/.github/workflows/lambda-deploy.yml) workflow on every push to `prod` and through `workflow_dispatch` (manual **Lambda Deploy** run).

Each deploy job builds a Linux `bootstrap` binary, uploads a versioned artifact to S3, and updates the function code via SSM parameters and shared actions under `.github/actions/`.

Current workers:

| Worker | Source (primary) | Deploy job | Concurrency group |
| - | - | - | - |
| activity-log | `apps/activity-log-lambda/**` | `activity_log_deploy` | `lambda-deploy-activity-log-…` |
| glossary-interchange | `apps/glossary-interchange-lambda/**` | `glossary_interchange_deploy` | `lambda-deploy-glossary-interchange-…` |
| memory-interchange | `apps/memory-interchange-lambda/**` | `memory_interchange_deploy` | `lambda-deploy-memory-interchange-…` |
| visual-context-match | `apps/visual-context-match-lambda/**` | `visual_context_match_deploy` | `lambda-deploy-visual-context-match-…` |

Concurrency groups append `${{ github.ref }}` (for example `refs/heads/prod`). Every deploy job uses the same AWS role session name: `github-actions-lambda-deploy`.

Infrastructure provisioning (queues, IAM, SSM parameter names) lives in the infra repository. See [Activity-log SQS and Go Lambda infrastructure](../adr/2026-09-25-activity-log-sqs-lambda-infrastructure.md).

## No path filters

Every push to `prod` deploys every Lambda. Do not add `on.push.paths` or per-job path filters.

Path filters used to decide which workers to deploy. They drifted from the real Go import graph. For example, glossary-interchange imports `internal/objectstore` and memory-interchange imports `internal/activitylog`, but neither filter listed those packages. A change there would reach `prod` without redeploying the affected Lambda.

## Concurrency

Deploy jobs use per-lambda concurrency groups, for example `lambda-deploy-glossary-interchange-refs/heads/prod`, with `cancel-in-progress: true`. A newer push cancels only the same worker's in-progress deploy, and the newer run redeploys that worker.

Push deploys also run `ensure-deploy-main-tip` after checkout. It skips the job when `prod` has moved past the run's commit, so an older run never overwrites a newer deploy. `workflow_dispatch` runs skip the check.

### Rules when changing the workflow

* Do add a dedicated `concurrency` block on each deploy job when you add a new worker.
* Do not make deploy jobs conditional on changed paths.

Decision record: [Lambda deploy job-level concurrency](../adr/2026-10-07-lambda-deploy-job-concurrency.md).

## Adding a new worker

Use the [create-sqs-lambda-worker](https://github.com/hyperlocalise/hyperlocalise/blob/main/.agents/skills/create-sqs-lambda-worker/SKILL.md) skill. At minimum in `lambda-deploy.yml`:

1. Add a deploy job with `if: github.ref == 'refs/heads/prod'`.
2. Add job-level `concurrency` with a unique group name (`lambda-deploy-<worker>-${{ github.ref }}`).
3. Call `ensure-deploy-main-tip` after checkout.
4. Set `role-session-name: github-actions-lambda-deploy` on the new job’s `configure-aws-credentials` step (same value as every other deploy job on `prod`).

### Do not change when launching a new Lambda

When you add a worker, extend the workflow. Do not refactor existing deploy jobs or shared CI behavior.

* Do not use per-worker `role-session-name` values. All Lambda deploy jobs on `prod` use `github-actions-lambda-deploy` only.
* Do not change `role-session-name` on existing deploy jobs when adding a worker.
* Do not add path filters.
* Do not remove `ensure-deploy-main-tip` or per-job concurrency from existing workers.
* Do not change existing concurrency group names for workers already in production.

Copy an existing deploy job as a template, then limit edits to the new worker’s paths, tests, build targets, SSM parameters, artifact key, and concurrency group.

Root [`AGENTS.md`](https://github.com/hyperlocalise/hyperlocalise/blob/main/AGENTS.md) summarizes the same rules for automation.

## Operations

Open the completed deploy job on `prod`. The **Summarize** step writes function name, S3 URI, version id, and commit SHA to the job summary.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.