build-tools/fab/changes/260406-vhk4-migrate-workflows-github-actions/spec.md

Spec: Migrate Workflows to GitHub Actions

Change: 260406-vhk4-migrate-workflows-github-actions Created: 2026-04-06 Affected memory: None

Non-Goals

• Enabling Grype vulnerability scanning — intentionally left disabled
• Modifying non-GCP workflows (pr-lint-and-check.yml, push-code-test.yml, push-code-scan.yml, push-npm.yml, push-npm-from-container.yml)
• Changing the GCP authentication pattern (secrets/vars remain identical)
• Updating consuming repos' uses: references (out of scope for this repo)

Workflows: Archive Non-GCP Variants

Requirement: Archive legacy workflows

The system SHALL move the 4 non-GCP workflow files to .github/workflows/archive/ to preserve history without cluttering the active workflows directory.

Files to archive:

• .github/workflows/base-build-image.yml
• .github/workflows/dispatch-container-base.yml
• .github/workflows/push-container.yml
• .github/workflows/push-s3.yml

Scenario: Archive directory creation and file move

• GIVEN the 4 non-GCP workflow files exist in .github/workflows/
• WHEN the migration is applied
• THEN .github/workflows/archive/ directory SHALL exist
• AND all 4 files SHALL be moved to .github/workflows/archive/ with identical filenames
• AND the files SHALL no longer exist in .github/workflows/

Workflows: Rename GCP Variants

Requirement: Drop -gcp suffix from workflow filenames

The system SHALL rename the 4 GCP workflow files to remove the -gcp suffix, making them the canonical workflow files.

Current name	New name
base-build-image-gcp.yml	base-build-image.yml
dispatch-container-base-gcp.yml	dispatch-container-base.yml
push-container-gcp.yml	push-container.yml
push-s3-gcp.yml	push-s3.yml

Scenario: Rename after archive

• GIVEN the non-GCP files have been archived (no naming collision)
• WHEN the GCP files are renamed
• THEN each -gcp.yml file SHALL be renamed to the corresponding base name
• AND the original -gcp.yml files SHALL no longer exist
• AND the file contents SHALL be unchanged (rename only, no content modification at this stage)

Workflows: Fix S3 Upload Action

Requirement: Replace Gitea-hosted aws-cli-action

The push-s3.yml workflow (formerly push-s3-gcp.yml) SHALL replace the Gitea-hosted action reference with the aws-actions/configure-aws-credentials@v4 action plus an inline aws s3 cp command, matching the pattern established in the dg2n-core repo.

Scenario: AWS credentials configuration

• GIVEN push-s3.yml has been renamed from push-s3-gcp.yml
• WHEN the S3 upload steps are updated
• THEN the Upload cloud files step using https://git.gmetri.io/gmetribin/aws-cli-action@v1.0.0 SHALL be replaced with two steps:
  1. A Configure AWS credentials step using aws-actions/configure-aws-credentials@v4 with:
     • aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
     • aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
     • aws-region: ${{ vars.AWS_DEFAULT_REGION }}
  2. An Upload cloud files step using run: with inline aws s3 cp command

Scenario: AWS secret/var name casing

• GIVEN the current workflow uses lowercase secret names (secrets.aws_access_key_id, etc.)
• WHEN the S3 steps are replaced
• THEN all AWS secret and variable references SHALL use uppercase names:
  • secrets.AWS_ACCESS_KEY_ID (was secrets.aws_access_key_id)
  • secrets.AWS_SECRET_ACCESS_KEY (was secrets.aws_secret_access_key)
  • vars.AWS_DEFAULT_REGION (was vars.aws_default_region)
  • vars.AWS_UPLOAD_BUCKET (was vars.aws_upload_bucket)

Scenario: S3 upload command equivalence

• GIVEN the old action ran s3 cp --recursive --cache-control max-age=31536000 --storage-class 'STANDARD_IA' cloud/ s3://{bucket}/{repo}/{build_id}
• WHEN the inline command replaces it
• THEN the aws s3 cp command SHALL preserve all flags: --recursive, --cache-control max-age=31536000, --storage-class STANDARD_IA
• AND the destination path SHALL remain s3://${{ vars.AWS_UPLOAD_BUCKET }}/${{ env.REPO_SHORT_NAME }}/${{ steps.get-id.outputs.BUILD_ID }}

Workflows: Preserve Existing Behavior

Requirement: No functional changes to GCP auth

All 4 renamed workflows SHALL retain their existing GCP authentication steps unchanged:

• google-github-actions/auth@v2 with credentials_json: ${{ secrets.GCP_SA_KEY }}
• google-github-actions/setup-gcloud@v2 with project_id: ${{ vars.GCP_PROJECT_ID }}
• gcloud auth configure-docker ${{ vars.GCP_REGION }}-docker.pkg.dev

Scenario: GCP auth preserved after rename

• GIVEN any of the 4 renamed workflow files
• WHEN the file content is inspected
• THEN the GCP auth steps SHALL be identical to the original -gcp variant

Requirement: Runners use GitHub-hosted ubuntu-22.04

All workflows SHALL use runs-on: ubuntu-22.04 (GitHub-hosted runners). No self-hosted runner references.

Scenario: Runner specification

• GIVEN any workflow file in .github/workflows/ (excluding archive)
• WHEN the runs-on value is inspected
• THEN it SHALL be ubuntu-22.04

Requirement: Grype scanning remains disabled

All workflows SHALL keep Grype vulnerability scanning commented out. No uncommented anchore/scan-action steps.

Scenario: Grype stays commented

• GIVEN any workflow that previously had Grype scanning commented out
• WHEN the migration is complete
• THEN the Grype scanning steps SHALL remain commented out

Assumptions

#	Grade	Decision	Rationale	Scores
1	Certain	Non-GCP workflows archived to .github/workflows/archive/, not deleted	Confirmed from intake #1 — user explicit	S:95 R:90 A:95 D:90
2	Certain	GCP workflows renamed to drop -gcp suffix	Confirmed from intake #2 — user explicit	S:95 R:85 A:90 D:85
3	Certain	Grype scanning stays disabled (commented out)	Confirmed from intake #3 — user explicit	S:95 R:90 A:95 D:95
4	Certain	Use aws-actions/configure-aws-credentials@v4 + inline aws s3 cp	Confirmed from intake #4 — matches dg2n-core reference	S:95 R:90 A:90 D:85
5	Certain	AWS secret/var names uppercased to match dg2n-core	Confirmed from intake #5 — user said dg2n-core is correct	S:90 R:85 A:90 D:85
6	Certain	GitHub-hosted ubuntu-22.04 runners	Confirmed from intake #6 — already the value in all workflows	S:95 R:90 A:95 D:90
7	Certain	S3 upload hybrid (GCP Docker + AWS S3) stays as-is	Confirmed from intake #7 — user explicit	S:90 R:85 A:90 D:90
8	Certain	Other 5 workflows unchanged	Upgraded from intake #8 Confident — user confirmed explicitly	S:90 R:85 A:90 D:85
9	Confident	Archive folder path is .github/workflows/archive/	Carried from intake #9 — user said "archive folder", path is reasonable convention	S:80 R:85 A:85 D:80
10	Certain	Archive must happen before rename to avoid filename collisions	Ordering constraint derived from spec — both old and new files share the same base names	S:95 R:95 A:95 D:95

10 assumptions (9 certain, 1 confident, 0 tentative, 0 unresolved).