diff --git a/README.md b/README.md index b8c8919..678053d 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,105 @@ -# workflows +# frmscoe/workflows -> **⚠️ This repository is a subordinate mirror of [tazama-lf/workflows](https://github.com/tazama-lf/workflows).** +> **⚠️ This repository is a downstream mirror of [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows), which is the canonical source for all Tazama GitHub Actions workflows.** > -> All workflow changes must be made in `tazama-lf/workflows` first. The `sync-workflows.yml` workflow in that repo propagates updates here automatically. **Do not edit workflow files in this repo directly** — any direct changes will be overwritten on the next sync. +> **All workflow changes must originate in `tazama-lf/workflows`.** There is no automated sync between the two workflow repos — changes must be applied here manually after merging in `tazama-lf/workflows`. **Do not edit workflow files in this repo directly** without a corresponding change upstream. -This repository holds the GitHub Actions workflows used by `frmscoe` organisation repositories. Workflows are gated on PRs to `dev` and `main`. +For complete SDLC documentation, repository class definitions, workflow reference tables, routine maintenance procedures, and known issues, see the **[`tazama-lf/workflows` README](https://github.com/tazama-lf/workflows/blob/dev/README.md)**. + +--- + +## What this repo is + +This repository holds the GitHub Actions workflows distributed to all active `frmscoe` organisation repositories (33 rule repos). It is a manually-maintained subset of `tazama-lf/workflows`, adapted for the `frmscoe` org context. + +--- + +## Cascade and dependency + +Changes flow in one direction: + +``` +tazama-lf/workflows → (manual PR) → frmscoe/workflows → (auto sync on push:dev) → 33 frmscoe rule repos +``` + +1. A workflow change is developed and merged to `dev` in `tazama-lf/workflows`. +2. The same change is applied manually to `frmscoe/workflows` via a separate PR. +3. On merge to `dev` in `frmscoe/workflows`, `sync-workflows.yml` fires automatically (`push: dev`) and opens `sync-workflows-update` PRs in all 33 target rule repos. +4. Reviewers merge the sync PRs in each rule repo. + +> **Note:** Unlike `tazama-lf/workflows` (which triggers sync on every PR event before merge), `frmscoe/workflows` triggers sync only on `push: dev` — i.e. after merge. Sync PRs in rule repos accurately reflect merged changes. + +--- + +## Differences from tazama-lf/workflows + +| Aspect | `frmscoe/workflows` | `tazama-lf/workflows` | +|--------|--------------------|-----------------------| +| npm scope | `@frmscoe` | `@tazama-lf` | +| Docker caller stub org | `rule_org: "frmscoe"` | `rule_org: "tazama-lf"` | +| Sync trigger | `push: dev` (after merge) | `pull_request: [dev]` (on open/update) | +| Sync targets | 33 frmscoe rule repos | 26 tazama-lf repos | +| Sync segmentation | None — all repos receive the same file set | `SPECIFIC_REPOS` / `PUBLISH_REPOS` / `RULE_REPOS` groups | +| Missing workflows | `dockerfile-linter.yml`, `dockerhub-image-build.yml`, `dockerhub-image-build-rc.yml` | All canonical files present | + +--- + +## Workflows distributed to frmscoe rule repos + +All 33 rule repos receive: + +`branch-target-check.yml`, `codacy.yml`, `codeql.yml`, `conventional-commits.yml`, `dco-check.yml`, `dependency-review.yml`, `gpg-verify.yml`, `milestone.yml`, `njsscan.yml`, `publish.yml`, `release-train.yml`, `release.yml`, `sbom.yml`, `scorecard.yml`, `version-check.yml` + +Plus per-repo caller stubs for: `package-rule-rc.yml` (fires on `push: dev`) and `package-rule.yml` (fires on `push: main`) + +**Not distributed:** `sync-workflows.yml`, `node.js.yml` (each repo maintains its own copy), `package-rule*.yml` canonical reusable definitions (replaced with caller stubs) + +--- + +## Target repositories + +`rule-001`, `rule-002`, `rule-003`, `rule-004`, `rule-006`, `rule-007`, `rule-008`, `rule-010`, `rule-011`, `rule-016`, `rule-017`, `rule-018`, `rule-020`, `rule-021`, `rule-024`, `rule-025`, `rule-026`, `rule-027`, `rule-028`, `rule-030`, `rule-044`, `rule-045`, `rule-048`, `rule-054`, `rule-063`, `rule-074`, `rule-075`, `rule-076`, `rule-078`, `rule-083`, `rule-084`, `rule-090`, `rule-091` + +--- + +## Workflow documentation + +Individual workflow documentation is in [`workflow-docs/`](workflow-docs/). For workflows shared with `tazama-lf/workflows`, docs contain a redirect link to the canonical entry in that repo. Docs for frmscoe-specific behaviour (`publish.yml`, `package-rule*.yml`, `sync-workflows.yml`) are maintained here. + +| Doc | Status | +|-----|--------| +| [`branch-target-check.md`](workflow-docs/branch-target-check.md) | → tazama-lf docs | +| [`codacy.md`](workflow-docs/codacy.md) | → tazama-lf docs | +| [`codeql.md`](workflow-docs/codeql.md) | → tazama-lf docs | +| [`conventional-commits.md`](workflow-docs/conventional-commits.md) | → tazama-lf docs | +| [`dco-check.md`](workflow-docs/dco-check.md) | → tazama-lf docs (⚠️ known issue [#37](https://github.com/tazama-lf/workflows/issues/37)) | +| [`dependency-review.md`](workflow-docs/dependency-review.md) | → tazama-lf docs | +| [`dockerfile-linter.md`](workflow-docs/dockerfile-linter.md) | Not in frmscoe/workflows | +| [`dockerhub-image-build.md`](workflow-docs/dockerhub-image-build.md) | Not in frmscoe/workflows | +| [`gpg-verify.md`](workflow-docs/gpg-verify.md) | → tazama-lf docs | +| [`milestone.md`](workflow-docs/milestone.md) | → tazama-lf docs | +| [`njsscan.md`](workflow-docs/njsscan.md) | → tazama-lf docs | +| [`nodejs.md`](workflow-docs/nodejs.md) | → tazama-lf docs (⚠️ `NPM_SCOPE=@frmscoe`) | +| [`package-rule-rc.md`](workflow-docs/package-rule-rc.md) | frmscoe-specific | +| [`package-rule.md`](workflow-docs/package-rule.md) | frmscoe-specific | +| [`publish.md`](workflow-docs/publish.md) | frmscoe-specific (`@frmscoe` scope) | +| [`release-train.md`](workflow-docs/release-train.md) | → tazama-lf docs | +| [`release.md`](workflow-docs/release.md) | → tazama-lf docs | +| [`sbom.md`](workflow-docs/sbom.md) | → tazama-lf docs (⚠️ known issue [#39](https://github.com/tazama-lf/workflows/issues/39)) | +| [`scorecard.md`](workflow-docs/scorecard.md) | → tazama-lf docs | +| [`sync-workflows.md`](workflow-docs/sync-workflows.md) | frmscoe-specific | +| [`version-check.md`](workflow-docs/version-check.md) | → tazama-lf docs | + +--- + +## Updating this repo + +To apply a workflow change from `tazama-lf/workflows`: + +1. Confirm the source PR in `tazama-lf/workflows` is merged to `dev`. +2. Open a PR in this repo with the same changes, referencing the source PR. +3. Update the corresponding `workflow-docs/` entry if the frmscoe behaviour differs. +4. On merge to `dev`, `sync-workflows.yml` will open `sync-workflows-update` PRs in all 33 target repos. +5. Review and merge the sync PRs in each target repo. diff --git a/workflow-docs/branch-target-check.md b/workflow-docs/branch-target-check.md new file mode 100644 index 0000000..62a0599 --- /dev/null +++ b/workflow-docs/branch-target-check.md @@ -0,0 +1,9 @@ +# `branch-target-check.yml` + +> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see: +> +> **[`workflow-docs/branch-target-check.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/branch-target-check.md)** + +## frmscoe-specific notes + +_None — behaviour in `frmscoe` rule repos is identical to the canonical workflow._ diff --git a/workflow-docs/codacy.md b/workflow-docs/codacy.md index c27ee37..18d87cf 100644 --- a/workflow-docs/codacy.md +++ b/workflow-docs/codacy.md @@ -1,33 +1,9 @@ -## Workflow Name: Codacy Security Scan +# `codacy.yml` -#### Purpose: +> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see: +> +> **[`workflow-docs/codacy.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/codacy.md)** -- This workflow performs security scans on the codebase using Codacy and uploads the results in SARIF format to GitHub. +## frmscoe-specific notes -#### Trigger Events: - -`Push`: Runs on pushes to the dev and main branches. - -`Pull Requests`: Runs on pull requests targeting dev and main. - -`Scheduled`: Runs every Thursday at 00:17 UTC. - -#### Permissions: - -`contents: read`: Allows reading repository contents. - -`security-events`: write: Allows uploading SARIF results. - -`actions: read`: Required for private repositories to retrieve Action run status. - -- Runs on: ubuntu-latest - -#### Workflow Steps: - -- Checkout Code: Uses actions/checkout@v4 to clone the repository. - -- Run Codacy Analysis CLI: Executes Codacy's CLI to scan the codebase, generating a SARIF file. - -- Upload SARIF Results: Uploads the SARIF file to GitHub using github/codeql-action/upload-sarif@v3. - -- This workflow ensures that security issues in the codebase are identified and reported efficiently. +_None — behaviour in `frmscoe` rule repos is identical to the canonical workflow._ diff --git a/workflow-docs/codeql.md b/workflow-docs/codeql.md index b1e2f7b..179604a 100644 --- a/workflow-docs/codeql.md +++ b/workflow-docs/codeql.md @@ -1,36 +1,11 @@ -## Workflow Name: CodeQL +# `codeql.yml` -#### Purpose: +> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see: +> +> **[`workflow-docs/codeql.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/codeql.md)** -- This workflow automates the process of scanning code for vulnerabilities using GitHub's CodeQL analysis. +## frmscoe-specific notes -#### Trigger Events: - -`Push`: Runs on pushes to the dev and main branches. - -`Pull Requests`: Runs on pull requests targeting dev and main. - -`Scheduled`: Runs every Thursday at 00:34 UTC. - -#### Permissions: - -`actions: read` - -`contents: read` - -`security-events: write` - -#### Workflow Steps: - -- Checkout Repository: Uses actions/checkout@v4 to clone the repository. - -- Initialize CodeQL: Prepares the CodeQL environment for the specified languages. - -- Autobuild: Automatically builds the codebase (useful for compiled languages). - -- Perform CodeQL Analysis: Executes the CodeQL scan and uploads results. - -#### Language Support: -The workflow is configured to scan JavaScript code but can be extended to support other languages like Java, Python, Go, etc. +_None — behaviour in `frmscoe` rule repos is identical to the canonical workflow._ This setup ensures that your code is continuously analyzed for security vulnerabilities and quality issues. diff --git a/workflow-docs/conventional-commits.md b/workflow-docs/conventional-commits.md index 1042800..67a9e6d 100644 --- a/workflow-docs/conventional-commits.md +++ b/workflow-docs/conventional-commits.md @@ -1,25 +1,9 @@ -## Workflow Name: PR Conventional Commit Validation +# `conventional-commits.yml` -#### Purpose: +> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see: +> +> **[`workflow-docs/conventional-commits.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/conventional-commits.md)** -- This workflow automatically validates the title of a pull request (PR) to ensure it follows conventional commit guidelines. It also applies corresponding GitHub labels based on the commit type. +## frmscoe-specific notes -- Uses the ytanikin/PRConventionalCommits@1.1.0 action. - -- Validates the PR title against a set of predefined conventional commit types (e.g., feat, fix, docs). - -- Maps these types to corresponding GitHub labels and applies them to the PR. - -- Utilizes a GitHub token for authentication and label management. - -- This workflow helps enforce commit message conventions and improve PR management by automatically labeling PRs based on their titles. - -#### Trigger Events: - -`Pull Request Events`: The workflow is triggered when a pull request is opened, synchronized, reopened, or edited. - -#### Workflow Steps: - -- Checkout Code: Uses actions/checkout@v4 to check out the repository. - -- PR Conventional Commit Validation: +_None — behaviour in `frmscoe` rule repos is identical to the canonical workflow._ diff --git a/workflow-docs/dco-check.md b/workflow-docs/dco-check.md index 313b334..41549d9 100644 --- a/workflow-docs/dco-check.md +++ b/workflow-docs/dco-check.md @@ -1,25 +1,9 @@ -## Workflow Name: DCO (Developer Certificate of Origin) +# `dco-check.yml` -#### Purpose: +> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see: +> +> **[`workflow-docs/dco-check.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/dco-check.md)** -- This workflow automatically checks whether each commit in a pull request (PR) has a "Signed-off-by" line, ensuring compliance with the Developer Certificate of Origin (DCO). +## frmscoe-specific notes -- Retrieves commits between the head and base branches. - -- Verifies that each commit contains a "Signed-off-by" line. - -- Lists any non-compliant commits and fails the job if any are found. - -- This workflow enforces DCO compliance, ensuring that all contributions are properly signed off, indicating that the contributor agrees to the terms of the DCO. - -#### Trigger Events: - -`Pull Request`: The workflow triggers whenever a pull request event occurs (e.g., opened, updated). - -#### Workflow Steps: - -- Checkout Repository: - -- Set Up Environment Variables: - -- Check for DCO Sign-off: +⚠️ The `git log` range in this workflow is reversed — it checks commits in the base branch that are not in the head branch, rather than the PR's new commits. DCO sign-off is not currently being verified correctly. This is a known issue tracked in [tazama-lf/workflows#37](https://github.com/tazama-lf/workflows/issues/37). diff --git a/workflow-docs/dependency-review.md b/workflow-docs/dependency-review.md index dd211c7..f79f95b 100644 --- a/workflow-docs/dependency-review.md +++ b/workflow-docs/dependency-review.md @@ -1,25 +1,9 @@ -## Workflow Name: Dependency Review +# `dependency-review.yml` -#### Purpose: +> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see: +> +> **[`workflow-docs/dependency-review.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/dependency-review.md)** -- This workflow automatically reviews the dependencies of a project whenever a pull request (PR) is opened or updated, ensuring that new dependencies are checked for security vulnerabilities and other issues. +## frmscoe-specific notes -- This workflow helps maintain the security and stability of your project by automatically reviewing new or updated dependencies in pull requests. - -#### Trigger Events: - -`Pull Request`: The workflow runs whenever a pull request is created or updated. - -#### Permissions: - -`Contents`: read: Grants the action read-only access to the repository contents. - -- Runs on: ubuntu-latest - -#### Workflow Steps: - -- Checkout Repository: - -- Dependency Review: - -Uses actions/dependency-review-action@v4 to analyze the dependencies of the project and identify any potential issues. +_None — behaviour in `frmscoe` rule repos is identical to the canonical workflow._ diff --git a/workflow-docs/dockerfile-linter.md b/workflow-docs/dockerfile-linter.md index b4b33bb..3378d1e 100644 --- a/workflow-docs/dockerfile-linter.md +++ b/workflow-docs/dockerfile-linter.md @@ -1,37 +1,7 @@ -## Workflow Name: Hadolint +# `dockerfile-linter.yml` -#### Purpose: - -- This workflow automates the linting of Dockerfiles using Hadolint and uploads the results to GitHub in SARIF format for further analysis. - -- This workflow ensures that Dockerfiles are automatically checked for best practices and potential issues, with results easily accessible within GitHub. - -#### Trigger Events: - -`Push`: Runs on pushes to the dev and main branches. - -`Pull Request`: Runs on pull requests targeting the dev branch. - -`Scheduled`: Runs every Sunday at 13:17 UTC. - -#### Permissions: - -`Contents: read:` Grants read-only access to the repository contents. - -`Security-events: write:` Allows uploading SARIF results. - -`Actions: read:` Required for private repositories to retrieve Action run status. - -- Runs on: ubuntu-latest - -#### Workflow Steps: - -- Checkout Code - -- Run Hadolint - -Generates a SARIF file with the results. - -- Upload Analysis Results: - -Uses github/codeql-action/upload-sarif@v2 to upload the SARIF file to GitHub for security analysis and code scanning. +> **This workflow is not present in `frmscoe/workflows`.** +> +> `frmscoe` rule repos do not maintain Dockerfiles that are linted by a separate workflow. Docker image builds for rule repos are handled by the `package-rule-rc.yml` and `package-rule.yml` caller stubs distributed by `sync-workflows.yml`. +> +> For reference, see the canonical documentation in `tazama-lf/workflows`: [`workflow-docs/dockerfile-linter.md`](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/dockerfile-linter.md). diff --git a/workflow-docs/dockerhub-image-build.md b/workflow-docs/dockerhub-image-build.md index 2b79609..a59c04a 100644 --- a/workflow-docs/dockerhub-image-build.md +++ b/workflow-docs/dockerhub-image-build.md @@ -1,42 +1,7 @@ -## Workflow Name: Publish Docker Image +# `dockerhub-image-build.yml` -Purpose: - -- This workflow automates the process of building, tagging, and pushing Docker images to Docker Hub whenever a new release is published. - -#### Trigger Events: - -`Release`: The workflow is triggered when a release is published. - -#### Jobs: - -- push_to_registry: - -- Runs on: ubuntu-latest - -#### Permissions: - -`Packages: write:` Allows pushing packages to the Docker registry. - -`Contents: read:` Grants read access to the repository contents. - -`Attestations: write:` Allows writing attestations. - -`ID-Token: write:` Required for generating artifact attestations. - -#### Workflow Steps: - -- Check Out the Repo: - -- Log in to Docker Hub: - -Uses docker/login-action to authenticate with Docker Hub using credentials stored in GitHub Secrets. - -- Extract Metadata: - -Uses docker/metadata-action to generate Docker image tags and labels. - -- Build and Push Docker Image: - -Uses docker/build-push-action to build the Docker image and push it to Docker Hub with the generated tags and labels. -Generate Artifact Attestation: +> **This workflow is not present in `frmscoe/workflows`.** +> +> `frmscoe` rule repos do not use standalone Docker build workflows. Docker image builds are handled by the `package-rule-rc.yml` and `package-rule.yml` reusable workflows (called via caller stubs distributed by `sync-workflows.yml`). +> +> For reference, see the canonical documentation in `tazama-lf/workflows`: [`workflow-docs/dockerhub-image-build.md`](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/dockerhub-image-build.md). diff --git a/workflow-docs/gpg-verify.md b/workflow-docs/gpg-verify.md index c25a42f..90cb204 100644 --- a/workflow-docs/gpg-verify.md +++ b/workflow-docs/gpg-verify.md @@ -1,27 +1,9 @@ -## Workflow Name: GPG Verify +# `gpg-verify.yml` -#### Purpose: +> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see: +> +> **[`workflow-docs/gpg-verify.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/gpg-verify.md)** -- This workflow automatically verifies the GPG signatures of commits in a pull request, ensuring that all commits are signed and verified as part of the code review process. +## frmscoe-specific notes -- This workflow helps enforce the use of GPG-signed commits, adding an extra layer of security to the contribution process. - -- If any commit fails the GPG verification, the workflow fails, ensuring only verified commits are merged. - -#### Trigger Events: - -`Pull Request`: The workflow triggers whenever a pull request is opened or updated. - -- Runs on: ubuntu-latest - -#### Workflow Steps: - -- Checkout Repository: - -- Set Up Environment Variables: - -Captures the head and base references of the pull request and sets up necessary environment variables. - -- Check GPG Verification Status: - -Retrieves the list of commits in the pull request. For each commit, it checks the GPG verification status using GitHub's API. +_None — behaviour in `frmscoe` rule repos is identical to the canonical workflow._ diff --git a/workflow-docs/milestone.md b/workflow-docs/milestone.md index bfaf74e..fff191c 100644 --- a/workflow-docs/milestone.md +++ b/workflow-docs/milestone.md @@ -1,31 +1,9 @@ -## Workflow Name: Milestone Workflow +# `milestone.yml` -#### Purpose: +> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see: +> +> **[`workflow-docs/milestone.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/milestone.md)** -- This workflow is designed to close a specific milestone on GitHub and trigger a release workflow. It is manually triggered with a specified milestone ID. +## frmscoe-specific notes -- This workflow streamlines the process of managing milestones and automates the transition to the release process. - -#### Trigger Events: - -`Workflow Dispatch`: This workflow is triggered manually with a milestoneId input. - -- Runs on: ubuntu-latest - -#### Workflow Steps: - -- Checkout Repository: - -Uses actions/checkout@v2 to clone the repository. - -- Set Up Environment Variables: - -Sets up necessary environment variables, including the GitHub token, milestone number, and GitHub API URL. - -- Close Milestone: - -Uses the GitHub API to close the specified milestone. - -- Trigger Release Workflow: - -Triggers another workflow for releasing, passing the milestone number as a payload using the peter-evans/repository-dispatch@v1 action. +_None — behaviour in `frmscoe` rule repos is identical to the canonical workflow._ diff --git a/workflow-docs/njsscan.md b/workflow-docs/njsscan.md index aa60450..99ec187 100644 --- a/workflow-docs/njsscan.md +++ b/workflow-docs/njsscan.md @@ -1,32 +1,9 @@ -## Workflow Name: njsscan sarif +# `njsscan.yml` -#### Purpose: +> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see: +> +> **[`workflow-docs/njsscan.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/njsscan.md)** -- This GitHub workflow is designed to run the njsscan code scanning tool and upload the results as a SARIF (Static Analysis Results Interchange Format) report to GitHub. Here's a detailed breakdown of the workflow: +## frmscoe-specific notes -- This workflow ensures that every push and pull request to the dev and main branches, as well as a weekly scheduled run, triggers a security scan using njsscan. The results are then uploaded to GitHub in SARIF format, allowing the repository maintainers to review and address potential security issues. - -#### Trigger Events - -`push`: - -`branches: [ "dev", "main" ]`: The workflow will trigger whenever there is a push to the dev or main branches. - -`pull_request`: - -`branches: [ "dev", "main" ]`: The workflow will also trigger when a pull request is made targeting the dev or main branches. - -`schedule`: - -`cron: '17 17 * * 1'`: The workflow is scheduled to run automatically every Monday at 17:17 UTC. - - -#### permissions: - -`contents`: read: Grants read access to the repository contents for the entire workflow. - -#### Workflow Steps - -- Checkout the code - -- njsscan +_None — behaviour in `frmscoe` rule repos is identical to the canonical workflow._ diff --git a/workflow-docs/nodejs.md b/workflow-docs/nodejs.md index 6fe802d..844fde3 100644 --- a/workflow-docs/nodejs.md +++ b/workflow-docs/nodejs.md @@ -1,83 +1,12 @@ -## Workflow Name: Node.js CI +# `node.js.yml` -#### Purpose: +> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) as the base reference. For full documentation — including trigger details, job steps, and limitations — see: +> +> **[`workflow-docs/nodejs.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/nodejs.md)** +> +> **Note: `node.js.yml` is NOT synced to target repos by `sync-workflows.yml`.** Each repo maintains its own copy. -- This GitHub workflow is designed for Continuous Integration (CI) of a Node.js project. It includes three jobs: building the project, checking the code style, and running tests. Here's a detailed breakdown of the workflow: +## frmscoe-specific notes -#### Environment Variables - -`env`: - -`GH_TOKEN`: ${{ secrets.GITHUB_TOKEN }}: A secret token used to authenticate with GitHub, stored securely in GitHub secrets. -NPM_SCOPE`: "@frmscoe": The scope for the npm packages, typically used for scoped packages. - -``NPM_REGISTRY`: "https://npm.pkg.github.com/": The npm registry URL where the scoped packages are hosted. - -`NODE_ENV`: 'test': The environment variable used to specify the environment as 'test'. - -`STARTUP_TYPE`: 'nats': A custom environment variable indicating the type of startup, possibly related to the messaging system used in the project. - -#### Triggers Events - -`push`: - -`branches: [ "dev", "main" ]`: The workflow triggers on a push to the dev or main branches. - -`pull_request`: - -`branches: [ "dev", "main" ]`: The workflow also triggers when a pull request is opened targeting the dev or main branches. -Jobs - -- The workflow is divided into three jobs: `build`, `lint`, and `test`. - -1. Build Job - -#### build: - -- runs-on: ubuntu-latest: This job runs on the latest available version of Ubuntu. - -- steps: - -Checkout the code: - -Install dependencies: - -run: npm ci: Installs the project dependencies using npm in a clean environment. - -Run build: - -run: npm run build: Executes the build script to compile the project. - -2. Lint Job - -#### lint: - -- runs-on: ubuntu-latest: The job runs on the latest Ubuntu version. - -- steps: - -Checkout code: - -Install dependencies: - -Check linting: - -3. Test Job - -#### test: - -- runs-on: ubuntu-latest: The job runs on Ubuntu. - -steps: - -Checkout code: - -Install dependencies: - -Run tests: - -#### Summary - -- This workflow is a complete CI pipeline for a Node.js project. It tests the code on multiple Node.js versions, checks the code style, and runs the build process. - -- The environment variables and registry settings are configured to work with a specific npm scope hosted on GitHub. The workflow runs on pushes and pull requests to the dev and main branches, ensuring continuous integration of the project code. +- `NPM_SCOPE` is set to `@frmscoe` (instead of `@tazama-lf` as in the canonical file). +- All other behaviour is identical. diff --git a/workflow-docs/package-rule-rc.md b/workflow-docs/package-rule-rc.md new file mode 100644 index 0000000..d420f41 --- /dev/null +++ b/workflow-docs/package-rule-rc.md @@ -0,0 +1,71 @@ +# `package-rule-rc.yml` + +> This workflow exists in **both** `tazama-lf/workflows` and `frmscoe/workflows`. The reusable workflow logic is identical to the stable variant, but triggers on `push: dev` to produce an `:rc` Docker tag. Caller stubs reference `frmscoe/workflows` and pass `rule_org: "frmscoe"`. +> +> For the full workflow logic documentation and the `tazama-lf` variant, see [`workflow-docs/package-rule-rc.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/package-rule-rc.md). + +## Purpose + +Reusable workflow that builds and pushes an `:rc` Docker image for a `frmscoe` rule processor on merge to `dev`. Each rule repo holds a caller stub that invokes this reusable definition from `frmscoe/workflows`. + +--- + +## Caller stub (distributed to each rule repo by `sync-workflows.yml`) + +```yaml +# .github/workflows/package-rule-rc.yml (in each frmscoe rule repo — managed centrally) +on: + push: + branches: [dev] + workflow_dispatch: +jobs: + build: + uses: frmscoe/workflows/.github/workflows/package-rule-rc.yml@dev + with: + rule_number: "001" # zero-padded rule number, e.g. "001", "044" + rule_org: "frmscoe" + secrets: inherit +``` + +--- + +## Trigger (in each rule repo) + +| Event | Conditions | +|-------|-----------| +| `push` | branches: `[dev]` | +| `workflow_dispatch` | manual | + +--- + +## Required Secrets + +| Secret | Scope | Purpose | +|--------|-------|---------| +| `GH_TOKEN_LIB` | org | npm install for private packages | +| `DOCKER_USERNAME` | org | Docker Hub authentication | +| `DOCKER_PASSWORD` | org | Docker Hub authentication | +| `SLACK_WEBHOOK_URL` | org | Slack notification | + +--- + +## Sync Distribution + +| Group | Behaviour | +|-------|-----------| +| All `REPOS` (33 frmscoe rule repos) | Receives a caller stub | + +--- + +## Known Limitations / Notes + +- The comment block in the canonical `frmscoe/workflows/package-rule-rc.yml` file shows a `tazama-lf/workflows` caller stub example — this is incorrect; frmscoe rule repos should reference `frmscoe/workflows`. The caller stubs stamped by `sync-workflows.yml` are correct. +- `dependabot[bot]` actors are excluded. + +--- + +## Repository Overrides + +| Repository | Reason | +|-----------|--------| +| _(none)_ | _(caller stubs are identical across all 33 rule repos)_ | diff --git a/workflow-docs/package-rule.md b/workflow-docs/package-rule.md new file mode 100644 index 0000000..4f175c1 --- /dev/null +++ b/workflow-docs/package-rule.md @@ -0,0 +1,71 @@ +# `package-rule.yml` + +> This workflow exists in **both** `tazama-lf/workflows` and `frmscoe/workflows`. The reusable workflow logic is identical. The difference is that caller stubs distributed to `frmscoe` rule repos reference `frmscoe/workflows` and pass `rule_org: "frmscoe"`. +> +> For the full workflow logic documentation and the `tazama-lf` variant, see [`workflow-docs/package-rule.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/package-rule.md). + +## Purpose + +Reusable workflow that builds and pushes a stable Docker image for a `frmscoe` rule processor on merge to `main`. Produces both a versioned tag (`:X.Y.Z`) and a `:latest` moving pointer. Each rule repo holds a caller stub that invokes this reusable definition from `frmscoe/workflows`. + +--- + +## Caller stub (distributed to each rule repo by `sync-workflows.yml`) + +```yaml +# .github/workflows/package-rule.yml (in each frmscoe rule repo — managed centrally) +on: + push: + branches: [main] + workflow_dispatch: +jobs: + build: + uses: frmscoe/workflows/.github/workflows/package-rule.yml@dev + with: + rule_number: "001" # zero-padded rule number, e.g. "001", "044" + rule_org: "frmscoe" + secrets: inherit +``` + +--- + +## Trigger (in each rule repo) + +| Event | Conditions | +|-------|-----------| +| `push` | branches: `[main]` | +| `workflow_dispatch` | manual | + +--- + +## Required Secrets + +| Secret | Scope | Purpose | +|--------|-------|---------| +| `GH_TOKEN_LIB` | org | npm install for private packages | +| `DOCKER_USERNAME` | org | Docker Hub authentication | +| `DOCKER_PASSWORD` | org | Docker Hub authentication | +| `SLACK_WEBHOOK_URL` | org | Slack notification | + +--- + +## Sync Distribution + +| Group | Behaviour | +|-------|-----------| +| All `REPOS` (33 frmscoe rule repos) | Receives a caller stub; the canonical reusable definition stays in `frmscoe/workflows` | + +--- + +## Known Limitations / Notes + +- The comment block in the canonical `frmscoe/workflows/package-rule.yml` file shows a `tazama-lf/workflows` caller stub example — this is incorrect; frmscoe rule repos should reference `frmscoe/workflows`. The caller stubs stamped by `sync-workflows.yml` are correct. +- `dependabot[bot]` actors are excluded. + +--- + +## Repository Overrides + +| Repository | Reason | +|-----------|--------| +| _(none)_ | _(caller stubs are identical across all 33 rule repos)_ | diff --git a/workflow-docs/publish.md b/workflow-docs/publish.md new file mode 100644 index 0000000..1813f28 --- /dev/null +++ b/workflow-docs/publish.md @@ -0,0 +1,97 @@ +# `publish.yml` + +> This workflow exists in **both** `tazama-lf/workflows` and `frmscoe/workflows`. The logic is identical but the npm scope differs — this variant publishes under `@frmscoe`, not `@tazama-lf`. +> +> For the `tazama-lf` variant, see [`workflow-docs/publish.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/publish.md). + +## Purpose + +Publishes an npm package to GitHub Packages under the `@frmscoe` scope. Determines the dist-tag from the version in `package.json`: + +- Prerelease version (e.g. `1.2.3-rc.1`) → `rc` dist-tag (triggered manually from `dev`) +- Clean semver (e.g. `1.2.3`) → `latest` dist-tag (fires automatically on `push: main`) + +--- + +## Trigger + +| Event | Conditions | +|-------|-----------| +| `push` | branches: `[main]` | +| `workflow_dispatch` | manual | + +--- + +## Execution Context + +| Property | Value | +|----------|-------| +| Runner | `ubuntu-latest` | +| Node version | `20` | +| npm scope | `@frmscoe` | +| Registry | `https://npm.pkg.github.com/` | +| Permissions | `packages: write`, `contents: read` | + +--- + +## Jobs + +### `build-and-publish` + +1. `actions/checkout@v4` — with `GH_TOKEN_LIB` token +2. `actions/setup-node@v4` — Node 20, registry `https://npm.pkg.github.com/`, scope `@frmscoe` +3. Set up npm authentication (writes `_authToken` to `.npmrc`) +4. `npm ci` +5. `npm run build` +6. Publish — reads version from `package.json`; publishes under `rc` if prerelease, otherwise `latest` +7. Notify Slack + +--- + +## Required Secrets + +| Secret | Scope | Purpose | +|--------|-------|---------| +| `GH_TOKEN_LIB` | org | npm authentication and checkout | +| `SLACK_WEBHOOK_URL` | org | Slack notification | + +--- + +## Sync Distribution + +| Group | Behaviour | +|-------|-----------| +| All `REPOS` (33 frmscoe rule repos) | Receives this file | + +--- + +## Dependencies (pinned actions) + +| Action | Pinned SHA | Semver alias | +|--------|-----------|--------------| +| `actions/checkout` | tag ref `v4` | — | +| `actions/setup-node` | tag ref `v4` | — | + +--- + +## frmscoe vs tazama-lf differences + +| Property | `frmscoe/workflows` | `tazama-lf/workflows` | +|----------|--------------------|-----------------------| +| npm scope | `@frmscoe` | `@tazama-lf` | +| Published to | `frmscoe` GitHub Packages | `tazama-lf` GitHub Packages | + +--- + +## Known Limitations / Notes + +- `version-check.yml` blocks merging a prerelease version to `main`, ensuring only clean semver versions are published as `latest`. +- `dependabot[bot]` actors are excluded. + +--- + +## Repository Overrides + +| Repository | Reason | +|-----------|--------| +| _(none)_ | _(all synced repos use this version)_ | diff --git a/workflow-docs/release-train.md b/workflow-docs/release-train.md new file mode 100644 index 0000000..8ab1f61 --- /dev/null +++ b/workflow-docs/release-train.md @@ -0,0 +1,9 @@ +# `release-train.yml` + +> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see: +> +> **[`workflow-docs/release-train.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/release-train.md)** + +## frmscoe-specific notes + +_None — behaviour in `frmscoe` rule repos is identical to the canonical workflow._ diff --git a/workflow-docs/release.md b/workflow-docs/release.md index 8506c1a..2117990 100644 --- a/workflow-docs/release.md +++ b/workflow-docs/release.md @@ -1,45 +1,9 @@ -## GitHub Action Workflow Documentation: Release +# `release.yml` -#### Purpose +> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see: +> +> **[`workflow-docs/release.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/release.md)** -- This GitHub Action workflow, named Release Workflow, automates the process of creating a new release based on merged pull requests, generating a changelog, and updating relevant files like CHANGELOG.md and VERSION. +## frmscoe-specific notes -- The workflow is triggered by a repository_dispatch event, specifically of type release, which can be used to trigger the workflow programmatically. - -- This workflow is an automated process that handles the entire release lifecycle, including version bumping, changelog generation, and updating repository files. It's triggered by an external event, making it suitable for use with external tools or scripts that manage release processes. - -- The workflow is robust, ensuring that all necessary release tasks are completed consistently and accurately. - -#### Workflow Breakdown - -##### Trigger - -`on: repository_dispatch`: The workflow is triggered by a repository_dispatch event. - -`types: [release`]: The workflow listens for the release event type. - -`properties: milestone_number`: The workflow accepts a milestone_number property, which is a string representing the milestone ID associated with the release. - -#### Workflow Steps: - -- Checkout Repository: - -- Get the Latest Tag in the Repository: - -- Determine Release Type: - -- Bump Version: - -- Get Milestone Details: - -- Generate Changelog - -- Display Changelog: - -- Attach Changelog to Release: - -- Create Release: - -- Update CHANGELOG.md File: - -- Update VERSION File: +_None — behaviour in `frmscoe` rule repos is identical to the canonical workflow._ diff --git a/workflow-docs/sbom.md b/workflow-docs/sbom.md new file mode 100644 index 0000000..4a39c81 --- /dev/null +++ b/workflow-docs/sbom.md @@ -0,0 +1,9 @@ +# `sbom.yml` + +> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see: +> +> **[`workflow-docs/sbom.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/sbom.md)** + +## frmscoe-specific notes + +⚠️ `sbom.yml` runs `docker build` to produce the SBOM. `frmscoe` rule repos do not contain a `Dockerfile`, so this workflow fails on every `push: main` in rule repos. This is a known issue tracked in [tazama-lf/workflows#39](https://github.com/tazama-lf/workflows/issues/39). diff --git a/workflow-docs/scorecard.md b/workflow-docs/scorecard.md new file mode 100644 index 0000000..ba840d1 --- /dev/null +++ b/workflow-docs/scorecard.md @@ -0,0 +1,9 @@ +# `scorecard.yml` + +> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see: +> +> **[`workflow-docs/scorecard.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/scorecard.md)** + +## frmscoe-specific notes + +In `frmscoe/workflows`, `scorecard.yml` is distributed to all 33 rule repos (there is no `PUBLISH_REPOS` exclusion in the frmscoe sync). In `tazama-lf/workflows`, `scorecard.yml` is excluded from `PUBLISH_REPOS`; frmscoe has no equivalent segmentation. diff --git a/workflow-docs/sync-workflows.md b/workflow-docs/sync-workflows.md index 8b1e2f5..72fb3ef 100644 --- a/workflow-docs/sync-workflows.md +++ b/workflow-docs/sync-workflows.md @@ -1,40 +1,109 @@ -## GitHub Action Workflow Documentation: Sync Workflows +# `sync-workflows.yml` -#### Purpose +> The `sync-workflows.yml` in `frmscoe/workflows` has **different trigger behaviour and a different target set** from the canonical version in `tazama-lf/workflows`. This document covers the `frmscoe/workflows` variant. +> +> For the `tazama-lf/workflows` variant, see [`workflow-docs/sync-workflows.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/sync-workflows.md). -- This GitHub Action workflow automates the process of synchronizing workflow files across multiple repositories whenever a pull request (PR) is merged into the dev branch. +## Purpose -- This workflow ensures that all specified repositories maintain consistent CI/CD workflows by automatically syncing changes from a central repository when updates are made. +Propagates canonical workflow files from this repository to all 33 active `frmscoe` rule repos. Fires automatically on `push: dev` (i.e. after a PR is merged). All rule repos receive the same file set — there is no segmentation by repo type. Caller stubs for `package-rule*.yml` are stamped individually per repo with the correct rule number. -#### Trigger Event +--- -`pull_request` +## Trigger -`types: [closed]` - This workflow triggers when a pull request is closed. +| Event | Conditions | +|-------|-----------| +| `push` | branches: `[dev]` — fires after merge, not on PR open | +| `workflow_dispatch` | manual | -`branches: [ "dev" ]` - It specifically listens to pull requests merged into the dev branch. +> **Key difference from `tazama-lf/workflows`:** This variant triggers on `push: dev` (fires once, after merge). The `tazama-lf` variant triggers on all `pull_request` events to `dev` (fires on open and update, before merge). See [tazama-lf/workflows#36](https://github.com/tazama-lf/workflows/issues/36). +--- -#### Jobs +## Execution Context -- Job: sync +| Property | Value | +|----------|-------| +| Runner | `ubuntu-latest` | +| Target org | `frmscoe` | +| Target repos | 33 rule repos (active subset of `rule-001`–`rule-091`) | +| Segmentation | None — all repos receive the same file set | +| Typical duration | ~20–40 min | +| Permissions | default (plus `GH_TOKEN` for cross-repo operations) | -`Condition`: +--- -if: github.event.pull_request.merged == true - This job only runs if the pull request was successfully merged. +## Target Repos -- Runs on: ubuntu-latest - The job uses the latest Ubuntu runner. +`rule-001`, `rule-002`, `rule-003`, `rule-004`, `rule-006`, `rule-007`, `rule-008`, `rule-010`, `rule-011`, `rule-016`, `rule-017`, `rule-018`, `rule-020`, `rule-021`, `rule-024`, `rule-025`, `rule-026`, `rule-027`, `rule-028`, `rule-030`, `rule-044`, `rule-045`, `rule-048`, `rule-054`, `rule-063`, `rule-074`, `rule-075`, `rule-076`, `rule-078`, `rule-083`, `rule-084`, `rule-090`, `rule-091` -#### Workflow Steps +--- -- Checkout Central Workflows Repo +## Jobs -- Set up Git +### `Sync_All_Repos_Common_Workflows` -- Install GitHub CLI +**Steps:** -- Get PR author details +1. `actions/checkout@v4` — checks out this repo +2. `Set up Git` — configures git identity for commits +3. `Install GitHub CLI` — downloads and installs `gh` CLI v2.14.7 +4. `Get PR author details` — captures author name and email for commit attribution +5. `Sync Workflows to Other Repos` — main loop: + - Clones each rule repo from `https://github.com/frmscoe/` + - Checks out or creates the `sync-workflows-update` branch + - Copies all files from the bundle **except** `package-rule*.yml` canonical definitions + - Stamps a `package-rule-rc.yml` caller stub (referencing `frmscoe/workflows`, `push: [dev]`) + - Stamps a `package-rule.yml` caller stub (referencing `frmscoe/workflows`, `push: [main]`) + - Both stubs pass `rule_org: "frmscoe"` and the repo's zero-padded rule number + - Commits, pushes, opens `sync-workflows-update` PR targeting `dev` -- Sync Workflows to Other Repos +--- -- Cleanup: Temporary files used for GitHub CLI authentication are removed after the operation. +## Workflows excluded from the sync bundle + +| File | Reason | +|------|--------| +| `sync-workflows.yml` | Canonical-only; never distributed | +| `node.js.yml` | Each repo maintains its own copy | +| `package-rule*.yml` (canonical definitions) | Replaced with per-repo caller stubs (see above) | + +--- + +## Required Secrets + +| Secret | Scope | Purpose | +|--------|-------|-------| +| `GH_TOKEN` | org | Clone, push, and open PRs in target repos | +| `PR_REVIEWERS` | vars | Reviewer login(s) for sync PRs | + +--- + +## Sync Distribution + +| Group | Behaviour | +|-------|-----------| +| **Not synced** | This file is excluded from the sync bundle | + +--- + +## Dependencies (pinned actions) + +| Action | Pinned SHA | Semver alias | +|--------|-----------|----------| +| `actions/checkout` | tag ref `v4` | — | + +--- + +## Known Limitations / Notes + +- `gh` CLI is pinned to v2.14.7 via a hardcoded tarball URL; update the download URL and extracted paths in the `Install GitHub CLI` step when upgrading. +- This repo is a manually-maintained mirror of `tazama-lf/workflows`. Changes to shared workflow files must originate in `tazama-lf/workflows` and be applied here separately — there is no automated sync between the two workflow repos. +- `dependabot[bot]` actors are excluded. + +--- + +## Repository Overrides + +Not applicable — this workflow is canonical-only and is never distributed. diff --git a/workflow-docs/version-check.md b/workflow-docs/version-check.md new file mode 100644 index 0000000..283c770 --- /dev/null +++ b/workflow-docs/version-check.md @@ -0,0 +1,9 @@ +# `version-check.yml` + +> This workflow is distributed from [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) without modification. For full documentation — including trigger details, job steps, required secrets, and known limitations — see: +> +> **[`workflow-docs/version-check.md` in tazama-lf/workflows](https://github.com/tazama-lf/workflows/blob/dev/workflow-docs/version-check.md)** + +## frmscoe-specific notes + +_None — behaviour in `frmscoe` rule repos is identical to the canonical workflow._