From 8daa017d63db3d79e4a989973e92f3b00e782417 Mon Sep 17 00:00:00 2001 From: Eleftherios Zisis Date: Thu, 30 Jul 2026 14:43:58 +0200 Subject: [PATCH 1/4] Add release and deploy workflows to agent rules. Document calver tagging with approval gates and terraform image bump PRs so agents can run release/deploy consistently. --- .amazonq/rules/project.md | 85 +++++++++++++++++++++++++++++++++++++++ AGENTS.md | 85 +++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 85 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 255 insertions(+) diff --git a/.amazonq/rules/project.md b/.amazonq/rules/project.md index a62f0dbb..b543843a 100644 --- a/.amazonq/rules/project.md +++ b/.amazonq/rules/project.md @@ -105,3 +105,88 @@ Use `tests/test_species.py` or `tests/test_subject.py` as reference for new enti ### S3 / Assets in Tests - Mocked with `moto` (`mock_aws`), session-scoped - Use `upload_entity_asset(client, entity_type, entity_id, files, label)` to attach files + +## Release (entitycore) + +Triggered by the user message **release**. + +### Calver format + +`YYYY.M.N` — year, month (no zero-padding), sequential counter within the month starting at `0`. +Examples: `2026.7.13`, `2026.8.0`. + +### Next tag algorithm + +1. `YEAR` = current UTC year, `MONTH` = current UTC month (1–12). +2. List tags matching `YEAR.MONTH.*`; take the highest `N`. +3. Next tag = `YEAR.MONTH.(N+1)`, or `YEAR.MONTH.0` if none exist for this month. + +### Workflow (approval required) + +**Do not create or push a tag until the user explicitly approves.** + +1. Ensure `main` is checked out and up to date with `origin/main`. +2. Find the latest tag: `git describe --tags --abbrev=0`. +3. **Show a release preview** and stop for approval: + - Proposed tag (from the algorithm above). + - Commits since the latest tag: `git log ..main --oneline`. + - Image that will be built: `public.ecr.aws/openbraininstitute/entitycore:` (see `.github/workflows/publish.yml`). +4. Wait for explicit user approval (e.g. "yes", "approve", "go ahead"). +5. After approval only: + ```bash + git tag + git push origin + ``` +6. Confirm the `Build and publish the Docker image` workflow started for the new tag. +7. Tell the user they can run **deploy** once the image is published. + +## Deploy (entitycore → terraform) + +Triggered by the user message **deploy**. + +Requires a **released** entitycore tag (Docker image already in ECR). If no tag is given, use the latest git tag on `main`. + +### Target repository + +`https://github.com/openbraininstitute/aws-terraform-deployment` + +### Image URL format + +``` +public.ecr.aws/openbraininstitute/entitycore: +``` + +Update the `entitycore_svc_image_url` variable in the relevant `*.tfvars` files. + +| File | Environment | +|------|-------------| +| `staging.tfvars` | staging | +| `production.tfvars` | production | +| `sandbox-nse.tfvars` | sandbox NSE | +| `sandbox-hpc.tfvars` | sandbox HPC | +| `sandbox-benchmarks.tfvars` | sandbox benchmarks | + +**Ask which environment(s) to update** if the user did not specify. Default to `staging` only. + +### Workflow + +1. Confirm the tag and target environment(s). +2. Clone or update the terraform repo (sibling dir or temp): + ```bash + gh repo clone openbraininstitute/aws-terraform-deployment /tmp/aws-terraform-deployment + cd /tmp/aws-terraform-deployment && git checkout main && git pull + ``` +3. Create branch `entitycore-` (or `bump-entitycore-`). +4. In each chosen `*.tfvars`, set: + ``` + entitycore_svc_image_url = "public.ecr.aws/openbraininstitute/entitycore:" + ``` +5. Commit, push, and open a PR: + ```bash + git checkout -b entitycore- + git add + git commit -m "Update entitycore to " + git push -u origin entitycore- + gh pr create --title "Update entitycore to " --body "Bump entitycore_svc_image_url to ." + ``` +6. Return the PR URL to the user. diff --git a/AGENTS.md b/AGENTS.md index 3d707919..f528baae 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -103,3 +103,88 @@ Use `tests/test_species.py` or `tests/test_subject.py` as reference for new enti ### S3 / Assets in Tests - Mocked with `moto` (`mock_aws`), session-scoped - Use `upload_entity_asset(client, entity_type, entity_id, files, label)` to attach files + +## Release (entitycore) + +Triggered by the user message **release**. + +### Calver format + +`YYYY.M.N` — year, month (no zero-padding), sequential counter within the month starting at `0`. +Examples: `2026.7.13`, `2026.8.0`. + +### Next tag algorithm + +1. `YEAR` = current UTC year, `MONTH` = current UTC month (1–12). +2. List tags matching `YEAR.MONTH.*`; take the highest `N`. +3. Next tag = `YEAR.MONTH.(N+1)`, or `YEAR.MONTH.0` if none exist for this month. + +### Workflow (approval required) + +**Do not create or push a tag until the user explicitly approves.** + +1. Ensure `main` is checked out and up to date with `origin/main`. +2. Find the latest tag: `git describe --tags --abbrev=0`. +3. **Show a release preview** and stop for approval: + - Proposed tag (from the algorithm above). + - Commits since the latest tag: `git log ..main --oneline`. + - Image that will be built: `public.ecr.aws/openbraininstitute/entitycore:` (see `.github/workflows/publish.yml`). +4. Wait for explicit user approval (e.g. "yes", "approve", "go ahead"). +5. After approval only: + ```bash + git tag + git push origin + ``` +6. Confirm the `Build and publish the Docker image` workflow started for the new tag. +7. Tell the user they can run **deploy** once the image is published. + +## Deploy (entitycore → terraform) + +Triggered by the user message **deploy**. + +Requires a **released** entitycore tag (Docker image already in ECR). If no tag is given, use the latest git tag on `main`. + +### Target repository + +`https://github.com/openbraininstitute/aws-terraform-deployment` + +### Image URL format + +``` +public.ecr.aws/openbraininstitute/entitycore: +``` + +Update the `entitycore_svc_image_url` variable in the relevant `*.tfvars` files. + +| File | Environment | +|------|-------------| +| `staging.tfvars` | staging | +| `production.tfvars` | production | +| `sandbox-nse.tfvars` | sandbox NSE | +| `sandbox-hpc.tfvars` | sandbox HPC | +| `sandbox-benchmarks.tfvars` | sandbox benchmarks | + +**Ask which environment(s) to update** if the user did not specify. Default to `staging` only. + +### Workflow + +1. Confirm the tag and target environment(s). +2. Clone or update the terraform repo (sibling dir or temp): + ```bash + gh repo clone openbraininstitute/aws-terraform-deployment /tmp/aws-terraform-deployment + cd /tmp/aws-terraform-deployment && git checkout main && git pull + ``` +3. Create branch `entitycore-` (or `bump-entitycore-`). +4. In each chosen `*.tfvars`, set: + ``` + entitycore_svc_image_url = "public.ecr.aws/openbraininstitute/entitycore:" + ``` +5. Commit, push, and open a PR: + ```bash + git checkout -b entitycore- + git add + git commit -m "Update entitycore to " + git push -u origin entitycore- + gh pr create --title "Update entitycore to " --body "Bump entitycore_svc_image_url to ." + ``` +6. Return the PR URL to the user. diff --git a/CLAUDE.md b/CLAUDE.md index a62f0dbb..b543843a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -105,3 +105,88 @@ Use `tests/test_species.py` or `tests/test_subject.py` as reference for new enti ### S3 / Assets in Tests - Mocked with `moto` (`mock_aws`), session-scoped - Use `upload_entity_asset(client, entity_type, entity_id, files, label)` to attach files + +## Release (entitycore) + +Triggered by the user message **release**. + +### Calver format + +`YYYY.M.N` — year, month (no zero-padding), sequential counter within the month starting at `0`. +Examples: `2026.7.13`, `2026.8.0`. + +### Next tag algorithm + +1. `YEAR` = current UTC year, `MONTH` = current UTC month (1–12). +2. List tags matching `YEAR.MONTH.*`; take the highest `N`. +3. Next tag = `YEAR.MONTH.(N+1)`, or `YEAR.MONTH.0` if none exist for this month. + +### Workflow (approval required) + +**Do not create or push a tag until the user explicitly approves.** + +1. Ensure `main` is checked out and up to date with `origin/main`. +2. Find the latest tag: `git describe --tags --abbrev=0`. +3. **Show a release preview** and stop for approval: + - Proposed tag (from the algorithm above). + - Commits since the latest tag: `git log ..main --oneline`. + - Image that will be built: `public.ecr.aws/openbraininstitute/entitycore:` (see `.github/workflows/publish.yml`). +4. Wait for explicit user approval (e.g. "yes", "approve", "go ahead"). +5. After approval only: + ```bash + git tag + git push origin + ``` +6. Confirm the `Build and publish the Docker image` workflow started for the new tag. +7. Tell the user they can run **deploy** once the image is published. + +## Deploy (entitycore → terraform) + +Triggered by the user message **deploy**. + +Requires a **released** entitycore tag (Docker image already in ECR). If no tag is given, use the latest git tag on `main`. + +### Target repository + +`https://github.com/openbraininstitute/aws-terraform-deployment` + +### Image URL format + +``` +public.ecr.aws/openbraininstitute/entitycore: +``` + +Update the `entitycore_svc_image_url` variable in the relevant `*.tfvars` files. + +| File | Environment | +|------|-------------| +| `staging.tfvars` | staging | +| `production.tfvars` | production | +| `sandbox-nse.tfvars` | sandbox NSE | +| `sandbox-hpc.tfvars` | sandbox HPC | +| `sandbox-benchmarks.tfvars` | sandbox benchmarks | + +**Ask which environment(s) to update** if the user did not specify. Default to `staging` only. + +### Workflow + +1. Confirm the tag and target environment(s). +2. Clone or update the terraform repo (sibling dir or temp): + ```bash + gh repo clone openbraininstitute/aws-terraform-deployment /tmp/aws-terraform-deployment + cd /tmp/aws-terraform-deployment && git checkout main && git pull + ``` +3. Create branch `entitycore-` (or `bump-entitycore-`). +4. In each chosen `*.tfvars`, set: + ``` + entitycore_svc_image_url = "public.ecr.aws/openbraininstitute/entitycore:" + ``` +5. Commit, push, and open a PR: + ```bash + git checkout -b entitycore- + git add + git commit -m "Update entitycore to " + git push -u origin entitycore- + gh pr create --title "Update entitycore to " --body "Bump entitycore_svc_image_url to ." + ``` +6. Return the PR URL to the user. From c01ebe8b188e455c6e6ef7f40c48be8da125d6f8 Mon Sep 17 00:00:00 2001 From: Eleftherios Zisis Date: Thu, 30 Jul 2026 14:46:12 +0200 Subject: [PATCH 2/4] Document combined release and deploy agent workflow. When the user asks for both, run release then open the terraform deploy PR for the new tag without waiting for a separate deploy message. --- .amazonq/rules/project.md | 16 +++++++++++++--- AGENTS.md | 16 +++++++++++++--- CLAUDE.md | 16 +++++++++++++--- 3 files changed, 39 insertions(+), 9 deletions(-) diff --git a/.amazonq/rules/project.md b/.amazonq/rules/project.md index b543843a..c7a050fe 100644 --- a/.amazonq/rules/project.md +++ b/.amazonq/rules/project.md @@ -138,13 +138,23 @@ Examples: `2026.7.13`, `2026.8.0`. git push origin ``` 6. Confirm the `Build and publish the Docker image` workflow started for the new tag. -7. Tell the user they can run **deploy** once the image is published. +7. If the user only said **release**, tell them they can run **deploy** once the image is published. + If they also said **deploy**, continue with the Deploy workflow below using the new tag (do not wait for a separate "deploy" message). + +## Release and deploy (combined) + +Triggered when the user message includes both **release** and **deploy** (e.g. "release and deploy"). + +1. Run the full **Release** workflow (preview → wait for approval → tag → push). +2. Immediately after the tag is pushed, run the **Deploy** workflow for that same tag (default `staging` unless the user named environments). +3. Return both results: the new tag / publish workflow status, and the terraform PR URL. +4. Note that the Docker image may still be building when the deploy PR is opened; merging the terraform PR should wait until the image is in ECR. ## Deploy (entitycore → terraform) -Triggered by the user message **deploy**. +Triggered by the user message **deploy**, or as the second step of **release and deploy**. -Requires a **released** entitycore tag (Docker image already in ECR). If no tag is given, use the latest git tag on `main`. +Requires a **released** entitycore tag. Prefer waiting until the Docker image is in ECR before merging the terraform PR; opening the PR may happen right after the tag is pushed when combined with release. If no tag is given, use the latest git tag on `main`. ### Target repository diff --git a/AGENTS.md b/AGENTS.md index f528baae..11b5610a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -136,13 +136,23 @@ Examples: `2026.7.13`, `2026.8.0`. git push origin ``` 6. Confirm the `Build and publish the Docker image` workflow started for the new tag. -7. Tell the user they can run **deploy** once the image is published. +7. If the user only said **release**, tell them they can run **deploy** once the image is published. + If they also said **deploy**, continue with the Deploy workflow below using the new tag (do not wait for a separate "deploy" message). + +## Release and deploy (combined) + +Triggered when the user message includes both **release** and **deploy** (e.g. "release and deploy"). + +1. Run the full **Release** workflow (preview → wait for approval → tag → push). +2. Immediately after the tag is pushed, run the **Deploy** workflow for that same tag (default `staging` unless the user named environments). +3. Return both results: the new tag / publish workflow status, and the terraform PR URL. +4. Note that the Docker image may still be building when the deploy PR is opened; merging the terraform PR should wait until the image is in ECR. ## Deploy (entitycore → terraform) -Triggered by the user message **deploy**. +Triggered by the user message **deploy**, or as the second step of **release and deploy**. -Requires a **released** entitycore tag (Docker image already in ECR). If no tag is given, use the latest git tag on `main`. +Requires a **released** entitycore tag. Prefer waiting until the Docker image is in ECR before merging the terraform PR; opening the PR may happen right after the tag is pushed when combined with release. If no tag is given, use the latest git tag on `main`. ### Target repository diff --git a/CLAUDE.md b/CLAUDE.md index b543843a..c7a050fe 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -138,13 +138,23 @@ Examples: `2026.7.13`, `2026.8.0`. git push origin ``` 6. Confirm the `Build and publish the Docker image` workflow started for the new tag. -7. Tell the user they can run **deploy** once the image is published. +7. If the user only said **release**, tell them they can run **deploy** once the image is published. + If they also said **deploy**, continue with the Deploy workflow below using the new tag (do not wait for a separate "deploy" message). + +## Release and deploy (combined) + +Triggered when the user message includes both **release** and **deploy** (e.g. "release and deploy"). + +1. Run the full **Release** workflow (preview → wait for approval → tag → push). +2. Immediately after the tag is pushed, run the **Deploy** workflow for that same tag (default `staging` unless the user named environments). +3. Return both results: the new tag / publish workflow status, and the terraform PR URL. +4. Note that the Docker image may still be building when the deploy PR is opened; merging the terraform PR should wait until the image is in ECR. ## Deploy (entitycore → terraform) -Triggered by the user message **deploy**. +Triggered by the user message **deploy**, or as the second step of **release and deploy**. -Requires a **released** entitycore tag (Docker image already in ECR). If no tag is given, use the latest git tag on `main`. +Requires a **released** entitycore tag. Prefer waiting until the Docker image is in ECR before merging the terraform PR; opening the PR may happen right after the tag is pushed when combined with release. If no tag is given, use the latest git tag on `main`. ### Target repository From 590f4fb169c2ad1ec86113c21610a71987062b10 Mon Sep 17 00:00:00 2001 From: Eleftherios Zisis Date: Thu, 30 Jul 2026 15:03:09 +0200 Subject: [PATCH 3/4] Use GitHub Releases with auto-generated notes for release. Match the UI release flow via gh release create --generate-notes instead of a bare tag push. --- .amazonq/rules/project.md | 20 +++++++++++--------- AGENTS.md | 20 +++++++++++--------- CLAUDE.md | 20 +++++++++++--------- 3 files changed, 33 insertions(+), 27 deletions(-) diff --git a/.amazonq/rules/project.md b/.amazonq/rules/project.md index c7a050fe..c36e0ef5 100644 --- a/.amazonq/rules/project.md +++ b/.amazonq/rules/project.md @@ -123,7 +123,7 @@ Examples: `2026.7.13`, `2026.8.0`. ### Workflow (approval required) -**Do not create or push a tag until the user explicitly approves.** +**Do not create the GitHub Release until the user explicitly approves.** 1. Ensure `main` is checked out and up to date with `origin/main`. 2. Find the latest tag: `git describe --tags --abbrev=0`. @@ -131,30 +131,32 @@ Examples: `2026.7.13`, `2026.8.0`. - Proposed tag (from the algorithm above). - Commits since the latest tag: `git log ..main --oneline`. - Image that will be built: `public.ecr.aws/openbraininstitute/entitycore:` (see `.github/workflows/publish.yml`). + - Note that GitHub will auto-generate the release title and notes. 4. Wait for explicit user approval (e.g. "yes", "approve", "go ahead"). -5. After approval only: +5. After approval only, create a GitHub Release (same as the UI “Generate release notes” → Publish): ```bash - git tag - git push origin + gh release create --generate-notes --target main ``` + This creates the tag on `main`, publishes the release with auto-generated notes, and triggers the Docker publish workflow. 6. Confirm the `Build and publish the Docker image` workflow started for the new tag. -7. If the user only said **release**, tell them they can run **deploy** once the image is published. +7. Return the release URL (`gh release view --json url -q .url`). +8. If the user only said **release**, tell them they can run **deploy** once the image is published. If they also said **deploy**, continue with the Deploy workflow below using the new tag (do not wait for a separate "deploy" message). ## Release and deploy (combined) Triggered when the user message includes both **release** and **deploy** (e.g. "release and deploy"). -1. Run the full **Release** workflow (preview → wait for approval → tag → push). -2. Immediately after the tag is pushed, run the **Deploy** workflow for that same tag (default `staging` unless the user named environments). -3. Return both results: the new tag / publish workflow status, and the terraform PR URL. +1. Run the full **Release** workflow (preview → wait for approval → GitHub Release with auto-generated notes). +2. Immediately after the release is published, run the **Deploy** workflow for that same tag (default `staging` unless the user named environments). +3. Return both results: the release URL / publish workflow status, and the terraform PR URL. 4. Note that the Docker image may still be building when the deploy PR is opened; merging the terraform PR should wait until the image is in ECR. ## Deploy (entitycore → terraform) Triggered by the user message **deploy**, or as the second step of **release and deploy**. -Requires a **released** entitycore tag. Prefer waiting until the Docker image is in ECR before merging the terraform PR; opening the PR may happen right after the tag is pushed when combined with release. If no tag is given, use the latest git tag on `main`. +Requires a **released** entitycore tag. Prefer waiting until the Docker image is in ECR before merging the terraform PR; opening the PR may happen right after the GitHub Release is published when combined with release. If no tag is given, use the latest git tag on `main`. ### Target repository diff --git a/AGENTS.md b/AGENTS.md index 11b5610a..8c4a8e81 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -121,7 +121,7 @@ Examples: `2026.7.13`, `2026.8.0`. ### Workflow (approval required) -**Do not create or push a tag until the user explicitly approves.** +**Do not create the GitHub Release until the user explicitly approves.** 1. Ensure `main` is checked out and up to date with `origin/main`. 2. Find the latest tag: `git describe --tags --abbrev=0`. @@ -129,30 +129,32 @@ Examples: `2026.7.13`, `2026.8.0`. - Proposed tag (from the algorithm above). - Commits since the latest tag: `git log ..main --oneline`. - Image that will be built: `public.ecr.aws/openbraininstitute/entitycore:` (see `.github/workflows/publish.yml`). + - Note that GitHub will auto-generate the release title and notes. 4. Wait for explicit user approval (e.g. "yes", "approve", "go ahead"). -5. After approval only: +5. After approval only, create a GitHub Release (same as the UI “Generate release notes” → Publish): ```bash - git tag - git push origin + gh release create --generate-notes --target main ``` + This creates the tag on `main`, publishes the release with auto-generated notes, and triggers the Docker publish workflow. 6. Confirm the `Build and publish the Docker image` workflow started for the new tag. -7. If the user only said **release**, tell them they can run **deploy** once the image is published. +7. Return the release URL (`gh release view --json url -q .url`). +8. If the user only said **release**, tell them they can run **deploy** once the image is published. If they also said **deploy**, continue with the Deploy workflow below using the new tag (do not wait for a separate "deploy" message). ## Release and deploy (combined) Triggered when the user message includes both **release** and **deploy** (e.g. "release and deploy"). -1. Run the full **Release** workflow (preview → wait for approval → tag → push). -2. Immediately after the tag is pushed, run the **Deploy** workflow for that same tag (default `staging` unless the user named environments). -3. Return both results: the new tag / publish workflow status, and the terraform PR URL. +1. Run the full **Release** workflow (preview → wait for approval → GitHub Release with auto-generated notes). +2. Immediately after the release is published, run the **Deploy** workflow for that same tag (default `staging` unless the user named environments). +3. Return both results: the release URL / publish workflow status, and the terraform PR URL. 4. Note that the Docker image may still be building when the deploy PR is opened; merging the terraform PR should wait until the image is in ECR. ## Deploy (entitycore → terraform) Triggered by the user message **deploy**, or as the second step of **release and deploy**. -Requires a **released** entitycore tag. Prefer waiting until the Docker image is in ECR before merging the terraform PR; opening the PR may happen right after the tag is pushed when combined with release. If no tag is given, use the latest git tag on `main`. +Requires a **released** entitycore tag. Prefer waiting until the Docker image is in ECR before merging the terraform PR; opening the PR may happen right after the GitHub Release is published when combined with release. If no tag is given, use the latest git tag on `main`. ### Target repository diff --git a/CLAUDE.md b/CLAUDE.md index c7a050fe..c36e0ef5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -123,7 +123,7 @@ Examples: `2026.7.13`, `2026.8.0`. ### Workflow (approval required) -**Do not create or push a tag until the user explicitly approves.** +**Do not create the GitHub Release until the user explicitly approves.** 1. Ensure `main` is checked out and up to date with `origin/main`. 2. Find the latest tag: `git describe --tags --abbrev=0`. @@ -131,30 +131,32 @@ Examples: `2026.7.13`, `2026.8.0`. - Proposed tag (from the algorithm above). - Commits since the latest tag: `git log ..main --oneline`. - Image that will be built: `public.ecr.aws/openbraininstitute/entitycore:` (see `.github/workflows/publish.yml`). + - Note that GitHub will auto-generate the release title and notes. 4. Wait for explicit user approval (e.g. "yes", "approve", "go ahead"). -5. After approval only: +5. After approval only, create a GitHub Release (same as the UI “Generate release notes” → Publish): ```bash - git tag - git push origin + gh release create --generate-notes --target main ``` + This creates the tag on `main`, publishes the release with auto-generated notes, and triggers the Docker publish workflow. 6. Confirm the `Build and publish the Docker image` workflow started for the new tag. -7. If the user only said **release**, tell them they can run **deploy** once the image is published. +7. Return the release URL (`gh release view --json url -q .url`). +8. If the user only said **release**, tell them they can run **deploy** once the image is published. If they also said **deploy**, continue with the Deploy workflow below using the new tag (do not wait for a separate "deploy" message). ## Release and deploy (combined) Triggered when the user message includes both **release** and **deploy** (e.g. "release and deploy"). -1. Run the full **Release** workflow (preview → wait for approval → tag → push). -2. Immediately after the tag is pushed, run the **Deploy** workflow for that same tag (default `staging` unless the user named environments). -3. Return both results: the new tag / publish workflow status, and the terraform PR URL. +1. Run the full **Release** workflow (preview → wait for approval → GitHub Release with auto-generated notes). +2. Immediately after the release is published, run the **Deploy** workflow for that same tag (default `staging` unless the user named environments). +3. Return both results: the release URL / publish workflow status, and the terraform PR URL. 4. Note that the Docker image may still be building when the deploy PR is opened; merging the terraform PR should wait until the image is in ECR. ## Deploy (entitycore → terraform) Triggered by the user message **deploy**, or as the second step of **release and deploy**. -Requires a **released** entitycore tag. Prefer waiting until the Docker image is in ECR before merging the terraform PR; opening the PR may happen right after the tag is pushed when combined with release. If no tag is given, use the latest git tag on `main`. +Requires a **released** entitycore tag. Prefer waiting until the Docker image is in ECR before merging the terraform PR; opening the PR may happen right after the GitHub Release is published when combined with release. If no tag is given, use the latest git tag on `main`. ### Target repository From 31b16e9031f45171febbca73a28cdddc81f07bf8 Mon Sep 17 00:00:00 2001 From: Eleftherios Zisis Date: Thu, 30 Jul 2026 23:16:45 +0200 Subject: [PATCH 4/4] Simplify release and deploy agent rules. --- .amazonq/rules/project.md | 102 +++++--------------------------------- AGENTS.md | 102 +++++--------------------------------- CLAUDE.md | 102 +++++--------------------------------- 3 files changed, 36 insertions(+), 270 deletions(-) diff --git a/.amazonq/rules/project.md b/.amazonq/rules/project.md index c36e0ef5..4220d8ba 100644 --- a/.amazonq/rules/project.md +++ b/.amazonq/rules/project.md @@ -106,99 +106,21 @@ Use `tests/test_species.py` or `tests/test_subject.py` as reference for new enti - Mocked with `moto` (`mock_aws`), session-scoped - Use `upload_entity_asset(client, entity_type, entity_id, files, label)` to attach files -## Release (entitycore) +## Release -Triggered by the user message **release**. +Triggered by **release**. Tag format `YYYY.M.N` (UTC year/month, no zero-pad; `N` = next after highest `YEAR.MONTH.*`, or `0`). -### Calver format +1. Update `main` from `origin/main`. +2. Preview and **stop for approval**: next tag, `git log ..main --oneline`, image `public.ecr.aws/openbraininstitute/entitycore:`. Do not release until approved. +3. `gh release create --generate-notes --target main` +4. Confirm Docker publish workflow started; return release URL. +5. If the message also includes **deploy**, continue with Deploy using this tag; otherwise tell the user they can **deploy** after the image is published. -`YYYY.M.N` — year, month (no zero-padding), sequential counter within the month starting at `0`. -Examples: `2026.7.13`, `2026.8.0`. +## Deploy -### Next tag algorithm +Triggered by **deploy**, or right after Release when both were requested. Tag = given tag, else latest on `main`. Image may still be building; merge terraform PR only after ECR has the image. -1. `YEAR` = current UTC year, `MONTH` = current UTC month (1–12). -2. List tags matching `YEAR.MONTH.*`; take the highest `N`. -3. Next tag = `YEAR.MONTH.(N+1)`, or `YEAR.MONTH.0` if none exist for this month. +Repo: `openbraininstitute/aws-terraform-deployment`. Set `entitycore_svc_image_url = "public.ecr.aws/openbraininstitute/entitycore:"` in the chosen `*.tfvars` (`staging.tfvars`, `production.tfvars`, `sandbox-nse.tfvars`, `sandbox-hpc.tfvars`, `sandbox-benchmarks.tfvars`). Ask for envs if unspecified; default **staging**. -### Workflow (approval required) - -**Do not create the GitHub Release until the user explicitly approves.** - -1. Ensure `main` is checked out and up to date with `origin/main`. -2. Find the latest tag: `git describe --tags --abbrev=0`. -3. **Show a release preview** and stop for approval: - - Proposed tag (from the algorithm above). - - Commits since the latest tag: `git log ..main --oneline`. - - Image that will be built: `public.ecr.aws/openbraininstitute/entitycore:` (see `.github/workflows/publish.yml`). - - Note that GitHub will auto-generate the release title and notes. -4. Wait for explicit user approval (e.g. "yes", "approve", "go ahead"). -5. After approval only, create a GitHub Release (same as the UI “Generate release notes” → Publish): - ```bash - gh release create --generate-notes --target main - ``` - This creates the tag on `main`, publishes the release with auto-generated notes, and triggers the Docker publish workflow. -6. Confirm the `Build and publish the Docker image` workflow started for the new tag. -7. Return the release URL (`gh release view --json url -q .url`). -8. If the user only said **release**, tell them they can run **deploy** once the image is published. - If they also said **deploy**, continue with the Deploy workflow below using the new tag (do not wait for a separate "deploy" message). - -## Release and deploy (combined) - -Triggered when the user message includes both **release** and **deploy** (e.g. "release and deploy"). - -1. Run the full **Release** workflow (preview → wait for approval → GitHub Release with auto-generated notes). -2. Immediately after the release is published, run the **Deploy** workflow for that same tag (default `staging` unless the user named environments). -3. Return both results: the release URL / publish workflow status, and the terraform PR URL. -4. Note that the Docker image may still be building when the deploy PR is opened; merging the terraform PR should wait until the image is in ECR. - -## Deploy (entitycore → terraform) - -Triggered by the user message **deploy**, or as the second step of **release and deploy**. - -Requires a **released** entitycore tag. Prefer waiting until the Docker image is in ECR before merging the terraform PR; opening the PR may happen right after the GitHub Release is published when combined with release. If no tag is given, use the latest git tag on `main`. - -### Target repository - -`https://github.com/openbraininstitute/aws-terraform-deployment` - -### Image URL format - -``` -public.ecr.aws/openbraininstitute/entitycore: -``` - -Update the `entitycore_svc_image_url` variable in the relevant `*.tfvars` files. - -| File | Environment | -|------|-------------| -| `staging.tfvars` | staging | -| `production.tfvars` | production | -| `sandbox-nse.tfvars` | sandbox NSE | -| `sandbox-hpc.tfvars` | sandbox HPC | -| `sandbox-benchmarks.tfvars` | sandbox benchmarks | - -**Ask which environment(s) to update** if the user did not specify. Default to `staging` only. - -### Workflow - -1. Confirm the tag and target environment(s). -2. Clone or update the terraform repo (sibling dir or temp): - ```bash - gh repo clone openbraininstitute/aws-terraform-deployment /tmp/aws-terraform-deployment - cd /tmp/aws-terraform-deployment && git checkout main && git pull - ``` -3. Create branch `entitycore-` (or `bump-entitycore-`). -4. In each chosen `*.tfvars`, set: - ``` - entitycore_svc_image_url = "public.ecr.aws/openbraininstitute/entitycore:" - ``` -5. Commit, push, and open a PR: - ```bash - git checkout -b entitycore- - git add - git commit -m "Update entitycore to " - git push -u origin entitycore- - gh pr create --title "Update entitycore to " --body "Bump entitycore_svc_image_url to ." - ``` -6. Return the PR URL to the user. +1. Clone/update repo on `main`, branch `entitycore-`. +2. Update tfvars, commit `Update entitycore to `, push, `gh pr create` with that title; return PR URL. diff --git a/AGENTS.md b/AGENTS.md index 8c4a8e81..73fc81a0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -104,99 +104,21 @@ Use `tests/test_species.py` or `tests/test_subject.py` as reference for new enti - Mocked with `moto` (`mock_aws`), session-scoped - Use `upload_entity_asset(client, entity_type, entity_id, files, label)` to attach files -## Release (entitycore) +## Release -Triggered by the user message **release**. +Triggered by **release**. Tag format `YYYY.M.N` (UTC year/month, no zero-pad; `N` = next after highest `YEAR.MONTH.*`, or `0`). -### Calver format +1. Update `main` from `origin/main`. +2. Preview and **stop for approval**: next tag, `git log ..main --oneline`, image `public.ecr.aws/openbraininstitute/entitycore:`. Do not release until approved. +3. `gh release create --generate-notes --target main` +4. Confirm Docker publish workflow started; return release URL. +5. If the message also includes **deploy**, continue with Deploy using this tag; otherwise tell the user they can **deploy** after the image is published. -`YYYY.M.N` — year, month (no zero-padding), sequential counter within the month starting at `0`. -Examples: `2026.7.13`, `2026.8.0`. +## Deploy -### Next tag algorithm +Triggered by **deploy**, or right after Release when both were requested. Tag = given tag, else latest on `main`. Image may still be building; merge terraform PR only after ECR has the image. -1. `YEAR` = current UTC year, `MONTH` = current UTC month (1–12). -2. List tags matching `YEAR.MONTH.*`; take the highest `N`. -3. Next tag = `YEAR.MONTH.(N+1)`, or `YEAR.MONTH.0` if none exist for this month. +Repo: `openbraininstitute/aws-terraform-deployment`. Set `entitycore_svc_image_url = "public.ecr.aws/openbraininstitute/entitycore:"` in the chosen `*.tfvars` (`staging.tfvars`, `production.tfvars`, `sandbox-nse.tfvars`, `sandbox-hpc.tfvars`, `sandbox-benchmarks.tfvars`). Ask for envs if unspecified; default **staging**. -### Workflow (approval required) - -**Do not create the GitHub Release until the user explicitly approves.** - -1. Ensure `main` is checked out and up to date with `origin/main`. -2. Find the latest tag: `git describe --tags --abbrev=0`. -3. **Show a release preview** and stop for approval: - - Proposed tag (from the algorithm above). - - Commits since the latest tag: `git log ..main --oneline`. - - Image that will be built: `public.ecr.aws/openbraininstitute/entitycore:` (see `.github/workflows/publish.yml`). - - Note that GitHub will auto-generate the release title and notes. -4. Wait for explicit user approval (e.g. "yes", "approve", "go ahead"). -5. After approval only, create a GitHub Release (same as the UI “Generate release notes” → Publish): - ```bash - gh release create --generate-notes --target main - ``` - This creates the tag on `main`, publishes the release with auto-generated notes, and triggers the Docker publish workflow. -6. Confirm the `Build and publish the Docker image` workflow started for the new tag. -7. Return the release URL (`gh release view --json url -q .url`). -8. If the user only said **release**, tell them they can run **deploy** once the image is published. - If they also said **deploy**, continue with the Deploy workflow below using the new tag (do not wait for a separate "deploy" message). - -## Release and deploy (combined) - -Triggered when the user message includes both **release** and **deploy** (e.g. "release and deploy"). - -1. Run the full **Release** workflow (preview → wait for approval → GitHub Release with auto-generated notes). -2. Immediately after the release is published, run the **Deploy** workflow for that same tag (default `staging` unless the user named environments). -3. Return both results: the release URL / publish workflow status, and the terraform PR URL. -4. Note that the Docker image may still be building when the deploy PR is opened; merging the terraform PR should wait until the image is in ECR. - -## Deploy (entitycore → terraform) - -Triggered by the user message **deploy**, or as the second step of **release and deploy**. - -Requires a **released** entitycore tag. Prefer waiting until the Docker image is in ECR before merging the terraform PR; opening the PR may happen right after the GitHub Release is published when combined with release. If no tag is given, use the latest git tag on `main`. - -### Target repository - -`https://github.com/openbraininstitute/aws-terraform-deployment` - -### Image URL format - -``` -public.ecr.aws/openbraininstitute/entitycore: -``` - -Update the `entitycore_svc_image_url` variable in the relevant `*.tfvars` files. - -| File | Environment | -|------|-------------| -| `staging.tfvars` | staging | -| `production.tfvars` | production | -| `sandbox-nse.tfvars` | sandbox NSE | -| `sandbox-hpc.tfvars` | sandbox HPC | -| `sandbox-benchmarks.tfvars` | sandbox benchmarks | - -**Ask which environment(s) to update** if the user did not specify. Default to `staging` only. - -### Workflow - -1. Confirm the tag and target environment(s). -2. Clone or update the terraform repo (sibling dir or temp): - ```bash - gh repo clone openbraininstitute/aws-terraform-deployment /tmp/aws-terraform-deployment - cd /tmp/aws-terraform-deployment && git checkout main && git pull - ``` -3. Create branch `entitycore-` (or `bump-entitycore-`). -4. In each chosen `*.tfvars`, set: - ``` - entitycore_svc_image_url = "public.ecr.aws/openbraininstitute/entitycore:" - ``` -5. Commit, push, and open a PR: - ```bash - git checkout -b entitycore- - git add - git commit -m "Update entitycore to " - git push -u origin entitycore- - gh pr create --title "Update entitycore to " --body "Bump entitycore_svc_image_url to ." - ``` -6. Return the PR URL to the user. +1. Clone/update repo on `main`, branch `entitycore-`. +2. Update tfvars, commit `Update entitycore to `, push, `gh pr create` with that title; return PR URL. diff --git a/CLAUDE.md b/CLAUDE.md index c36e0ef5..4220d8ba 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -106,99 +106,21 @@ Use `tests/test_species.py` or `tests/test_subject.py` as reference for new enti - Mocked with `moto` (`mock_aws`), session-scoped - Use `upload_entity_asset(client, entity_type, entity_id, files, label)` to attach files -## Release (entitycore) +## Release -Triggered by the user message **release**. +Triggered by **release**. Tag format `YYYY.M.N` (UTC year/month, no zero-pad; `N` = next after highest `YEAR.MONTH.*`, or `0`). -### Calver format +1. Update `main` from `origin/main`. +2. Preview and **stop for approval**: next tag, `git log ..main --oneline`, image `public.ecr.aws/openbraininstitute/entitycore:`. Do not release until approved. +3. `gh release create --generate-notes --target main` +4. Confirm Docker publish workflow started; return release URL. +5. If the message also includes **deploy**, continue with Deploy using this tag; otherwise tell the user they can **deploy** after the image is published. -`YYYY.M.N` — year, month (no zero-padding), sequential counter within the month starting at `0`. -Examples: `2026.7.13`, `2026.8.0`. +## Deploy -### Next tag algorithm +Triggered by **deploy**, or right after Release when both were requested. Tag = given tag, else latest on `main`. Image may still be building; merge terraform PR only after ECR has the image. -1. `YEAR` = current UTC year, `MONTH` = current UTC month (1–12). -2. List tags matching `YEAR.MONTH.*`; take the highest `N`. -3. Next tag = `YEAR.MONTH.(N+1)`, or `YEAR.MONTH.0` if none exist for this month. +Repo: `openbraininstitute/aws-terraform-deployment`. Set `entitycore_svc_image_url = "public.ecr.aws/openbraininstitute/entitycore:"` in the chosen `*.tfvars` (`staging.tfvars`, `production.tfvars`, `sandbox-nse.tfvars`, `sandbox-hpc.tfvars`, `sandbox-benchmarks.tfvars`). Ask for envs if unspecified; default **staging**. -### Workflow (approval required) - -**Do not create the GitHub Release until the user explicitly approves.** - -1. Ensure `main` is checked out and up to date with `origin/main`. -2. Find the latest tag: `git describe --tags --abbrev=0`. -3. **Show a release preview** and stop for approval: - - Proposed tag (from the algorithm above). - - Commits since the latest tag: `git log ..main --oneline`. - - Image that will be built: `public.ecr.aws/openbraininstitute/entitycore:` (see `.github/workflows/publish.yml`). - - Note that GitHub will auto-generate the release title and notes. -4. Wait for explicit user approval (e.g. "yes", "approve", "go ahead"). -5. After approval only, create a GitHub Release (same as the UI “Generate release notes” → Publish): - ```bash - gh release create --generate-notes --target main - ``` - This creates the tag on `main`, publishes the release with auto-generated notes, and triggers the Docker publish workflow. -6. Confirm the `Build and publish the Docker image` workflow started for the new tag. -7. Return the release URL (`gh release view --json url -q .url`). -8. If the user only said **release**, tell them they can run **deploy** once the image is published. - If they also said **deploy**, continue with the Deploy workflow below using the new tag (do not wait for a separate "deploy" message). - -## Release and deploy (combined) - -Triggered when the user message includes both **release** and **deploy** (e.g. "release and deploy"). - -1. Run the full **Release** workflow (preview → wait for approval → GitHub Release with auto-generated notes). -2. Immediately after the release is published, run the **Deploy** workflow for that same tag (default `staging` unless the user named environments). -3. Return both results: the release URL / publish workflow status, and the terraform PR URL. -4. Note that the Docker image may still be building when the deploy PR is opened; merging the terraform PR should wait until the image is in ECR. - -## Deploy (entitycore → terraform) - -Triggered by the user message **deploy**, or as the second step of **release and deploy**. - -Requires a **released** entitycore tag. Prefer waiting until the Docker image is in ECR before merging the terraform PR; opening the PR may happen right after the GitHub Release is published when combined with release. If no tag is given, use the latest git tag on `main`. - -### Target repository - -`https://github.com/openbraininstitute/aws-terraform-deployment` - -### Image URL format - -``` -public.ecr.aws/openbraininstitute/entitycore: -``` - -Update the `entitycore_svc_image_url` variable in the relevant `*.tfvars` files. - -| File | Environment | -|------|-------------| -| `staging.tfvars` | staging | -| `production.tfvars` | production | -| `sandbox-nse.tfvars` | sandbox NSE | -| `sandbox-hpc.tfvars` | sandbox HPC | -| `sandbox-benchmarks.tfvars` | sandbox benchmarks | - -**Ask which environment(s) to update** if the user did not specify. Default to `staging` only. - -### Workflow - -1. Confirm the tag and target environment(s). -2. Clone or update the terraform repo (sibling dir or temp): - ```bash - gh repo clone openbraininstitute/aws-terraform-deployment /tmp/aws-terraform-deployment - cd /tmp/aws-terraform-deployment && git checkout main && git pull - ``` -3. Create branch `entitycore-` (or `bump-entitycore-`). -4. In each chosen `*.tfvars`, set: - ``` - entitycore_svc_image_url = "public.ecr.aws/openbraininstitute/entitycore:" - ``` -5. Commit, push, and open a PR: - ```bash - git checkout -b entitycore- - git add - git commit -m "Update entitycore to " - git push -u origin entitycore- - gh pr create --title "Update entitycore to " --body "Bump entitycore_svc_image_url to ." - ``` -6. Return the PR URL to the user. +1. Clone/update repo on `main`, branch `entitycore-`. +2. Update tfvars, commit `Update entitycore to `, push, `gh pr create` with that title; return PR URL.