From e2dbcd76ebdcd5feed5ea9e850e4223b12fb7d08 Mon Sep 17 00:00:00 2001 From: Alexander Stein Date: Tue, 15 Mar 2022 15:20:04 -0400 Subject: [PATCH] Embed diagram of CI/CD workflow. (#1165) --- build/ci-cd/README.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/build/ci-cd/README.md b/build/ci-cd/README.md index 6d6afea2dc..933ae5057a 100644 --- a/build/ci-cd/README.md +++ b/build/ci-cd/README.md @@ -8,6 +8,41 @@ This GitHub repository uses a CI/CD process that provides automation for: Using a CI/CD process ensures that all artifacts in [pull requests](https://github.com/usnistgov/OSCAL/blob/master/CONTRIBUTING.md) and in the [master branch](https://github.com/usnistgov/OSCAL) are valid and usable. +## Workflow + +The NIST OSCAL repository provide scripts and orchestrates them through [GitHub Actions job declarations]. Below is a diagram illustrating the tasks an OSCAL stakeholder will want to perform and the relevant GitHub Actions jobs and scripts they trigger. + +```mermaid +graph TD + Dev[I'm a developer] + --> ChoiceAction{and I want to?} + %% ChoiceAction stepper + ChoiceAction -->|change the Metaschema models| EditMetaschemaModels(update the Metaschema model) + ChoiceAction -->|change OSCAL models| EditModels(edit the OSCAL models) + ChoiceAction -->|change the website documentation| EditWebsite(update the website content) + ChoiceAction -->|deploy the website to pages.nist.gov| PublishWebsite(check for relevant git branch) + ChoiceAction -->|publish an OSCAL release| PublishRelease(select relevant changes) + %% I want to edit the OSCAL models + EditModels -->|push to GitHub and trigger Actions| PipelineMetaschemaArtifacts(fab:fa-github metaschema-artifacts.yaml) + PipelineMetaschemaArtifacts -->|trigger first script| GenerateSchemas(fas:fa-terminal generate-schema.sh) + GenerateSchemas -->|update content converters| GenerateContentConverters(fas:fa-terminal generate-content-converters.sh) + GenerateContentConverters -->|test the changes| RunUnitTests(fas:fa-terminal run-unittests.sh) + RunUnitTests -->|publish auto-converted artifacts| GitAutoCommitAction(fab:fa-github stefanzweifel/git-auto-commit-action) + GitAutoCommitAction --> Done(Done, good job!) + %% I want to change the website documentation + EditWebsite -->|push to GitHub and trigger Actions| PipelineWebsiteArtifacts(fab:fa-github website-artifacts.yaml) + PipelineWebsiteArtifacts -->|trigger first script| GenerateSpecificationDocs(fas:fa-terminal generate-specification-documentation.sh) + GenerateSpecificationDocs -->|upload converted specs XML to HTML| UploadArtifact(fab:fa-github actions/upload-artifact) + UploadArtifact -->|build website with site generator| BuildWebsiteSSG(fas:fa-terminal hugo) + BuildWebsiteSSG -->|upload converted Markdown to HTML| UploadArtifact(fab:fa-github actions/upload-artifact) + UploadArtifact -->|check hyperlinks are valid| CheckHyperlinks(fab:fa-github untitaker/hyperlink) + CheckHyperlinks -->|publish artifacts| GitAutoCommitAction + %% I want to deploy the website + PublishWebsite -->|push to GitHub and trigger Actions| PipelineDeployWebsite(fab:fa-github website-deploy.yaml) + PipelineDeployWebsite -->|trigger first script| DeployWebsite(fas:fa-terminal deploy.sh) + %% I want to publish an OSCAL release +``` + ## Provided Scripts The primary CircleCI supported CI/CD workflow, ```build```, is uses a series of bash scripts. The following scripts are used in this workflow for all PRs that are submitted: