# ipdxco/unified-github-workflows architecture

> Architecture diagram of the GitHub repository ipdxco/unified-github-workflows, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ipdxco/unified-github-workflows
- Repository: https://github.com/ipdxco/unified-github-workflows

## Overview

##### Project type and purpose
- This is a **DevOps orchestration** project (Unified CI) that lives in a single GitHub repo and automates:
- Rendering and distributing workflow templates
- Opening and merging PRs in participating repos
- Versioning and releasing its own code
- It leverages custom composite Actions, shell scripts, and GitHub’s REST/GraphQL APIs.

##### File structure
- Top-level areas:
- **.github/actions/**: composite Action definitions (inspect-releaser, read-config, read-go-mod, render-templates, etc.)
- **.github/workflows/**: reusable workflow definitions (copy-templates, create-prs, merge-prs, sync-forks, release workflows, tagpush, etc.)
- **templates/**: YAML templates shipped into target repos
- **scripts/**: Bash scripts invoked by workflows and Actions
- **defaults.yml**: the default config driving template rendering
- **version.json**, **CHANGELOG.md**, **LICENSE**: versioning and metadata
- Key patterns:
- **Composite actions** for modular steps
- **Reusable workflows** invoked from target repos
- **Scheduled and event-driven pipelines**

##### README insights
- Describes two main domains:
1. **Template distribution pipelines** (copy, create-PR, merge-PR, sync forks)
2. **Versioning pipelines** (release-check, releaser, tagpush)
- Emphasizes config layering: defaults.yml + per-repo `.github/uci.yml` or job-specific JSON files.

##### Main components & interactions
a. Components
1. **Unified CI Repository**
- Stores **Templates**, **Defaults**, **Scripts**, **Actions**, **Workflows**
2. **GitHub Actions Runner**
- Executes workflows on schedule or triggers
3. **Custom Composite Actions**
- E.g., render-templates: merges defaults, templates, repo config → final workflows
4. **Shell Scripts**
- Utility scripts (copy-templates.sh, update-go.sh, etc.)
5. **GitHub API**
- Used by create-prs, merge-prs, tagpush workflows
6. **Participating Repositories**
- Receive rendered workflows via PRs
b. Interactions
- **Schedule trigger** fires `copy-templates.yml`
→ Runner loads `defaults.yml` + optional `.github/uci.yml` from each target repo
→ `render-templates` action + scripts produce concrete workflow YAMLs
→ `copy-templates` commits changes into target repos via PR (GitHub API)
- **Create-PR** opens PRs for updated workflows
- **Merge-PR** auto-merges when checks pass
- **Sync-forks** keeps forks in sync if using organization-specific forks
- **Release pipelines** manage Unified CI’s own version.json:
– `release-check.yml` posts draft release and diagnostics
– `releaser.yml` publishes GH Release on merge
– `tagpush.yml` validates any manual tag pushes
c. Architectural patterns
- **Event-driven pipelines**: scheduled, push, PR events
- **Template rendering**: uses composite actions to abstract common logic
- **Configuration layering**: defaults → repo override → job override
- **Reusable workflows**: DRY, centrally maintained
d. Key technologies
- GitHub Actions (YAML workflows, composite actions)
- Bash scripting
- GitHub REST/GraphQL API
- YAML templating (workflow templates + defaults.yml)

##### Don’t overthink—capture all essential pieces
- Configuration sources separately (default vs per-repo vs job-specific)
- How reusable workflows in `.github/workflows/` are referenced by templates

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "Unified CI Repo"
    templates[/templates/]:::static
    defaults["defaults.yml"]:::static
    versionData["templates/version.json"]:::static
    changelog["CHANGELOG.md"]:::static
    licenseAP["LICENSE-APACHE"]:::static
    licenseMIT["LICENSE-MIT"]:::static

    subgraph "Composite Actions"
      inspectReleaser["Inspect Releaser Action"]:::action
      readConfig["Read Config Action"]:::action
      readGoMod["Read Go Mod Action"]:::action
      renderTemplates["Render Templates Action"]:::action
    end

    subgraph "Shell Scripts"
      copyScript["copy-templates.sh"]:::action
      renderScript["render-template.sh"]:::action
      deleteScript["delete-templates.sh"]:::action
      updateGo["update-go.sh"]:::action
      closePRs["close-prs.sh"]:::action
    end

    subgraph "Workflows"
      copyTemplatesWF["Copy Templates Workflow"]:::workflow
      createPRsWF["Create PRs Workflow"]:::workflow
      mergePRsWF["Merge PRs Workflow"]:::workflow
      syncForksWF["Sync Forks Workflow"]:::workflow
      releaseCheckWF["Release Check Workflow"]:::workflow
      releaserWF["Releaser Workflow"]:::workflow
      tagpushWF["Tagpush Workflow"]:::workflow
    end
  end

  subgraph "GitHub Actions Runner"
    GHRunner["GitHub Actions Runner"]:::runner
  end

  subgraph "Target Repos"
    TargetRepos["Participating Repositories"]:::repo
  end

  GitHubAPI["GitHub API"]:::api

  %% Workflow executions
  copyTemplatesWF -->|runs on| GHRunner
  createPRsWF -->|runs on| GHRunner
  mergePRsWF -->|runs on| GHRunner
  syncForksWF -->|runs on| GHRunner
  releaseCheckWF -->|runs on| GHRunner
  releaserWF -->|runs on| GHRunner
  tagpushWF -->|runs on| GHRunner

  %% Runner invokes actions & scripts
  GHRunner --> renderTemplates
  GHRunner --> readConfig
  GHRunner --> readGoMod
  GHRunner --> inspectReleaser

  GHRunner --> copyScript
  GHRunner --> renderScript
  GHRunner --> deleteScript
  GHRunner --> updateGo
  GHRunner --> closePRs

  %% Static assets consumed
  renderTemplates --> defaults
  renderTemplates --> templates
  renderTemplates --> versionData

  copyTemplatesWF -->|uses| renderTemplates
  copyTemplatesWF -->|executes| copyScript
  createPRsWF -->|executes| closePRs
  mergePRsWF -->|executes| closePRs

  %% API interactions
  GHRunner -->|calls| GitHubAPI
  GitHubAPI -->|opens PRs| TargetRepos
  GitHubAPI -->|merges PRs| TargetRepos
  GitHubAPI -->|updates tags/releases| TargetRepos

  %% Click Events
  click inspectReleaser "https://github.com/ipdxco/unified-github-workflows/blob/main/.github/actions/inspect-releaser/action.yml"
  click readConfig "https://github.com/ipdxco/unified-github-workflows/blob/main/.github/actions/read-config/action.yml"
  click readGoMod "https://github.com/ipdxco/unified-github-workflows/blob/main/.github/actions/read-go-mod/action.yml"
  click renderTemplates "https://github.com/ipdxco/unified-github-workflows/blob/main/.github/actions/render-templates/action.yml"

  click copyTemplatesWF "https://github.com/ipdxco/unified-github-workflows/blob/main/.github/workflows/copy-templates.yml"
  click createPRsWF "https://github.com/ipdxco/unified-github-workflows/blob/main/.github/workflows/create-prs.yml"
  click mergePRsWF "https://github.com/ipdxco/unified-github-workflows/blob/main/.github/workflows/merge-prs.yml"
  click syncForksWF "https://github.com/ipdxco/unified-github-workflows/blob/main/.github/workflows/sync-forks.yml"
  click releaseCheckWF "https://github.com/ipdxco/unified-github-workflows/blob/main/.github/workflows/release-check.yml"
  click releaserWF "https://github.com/ipdxco/unified-github-workflows/blob/main/.github/workflows/releaser.yml"
  click tagpushWF "https://github.com/ipdxco/unified-github-workflows/blob/main/.github/workflows/tagpush.yml"

  click copyScript "https://github.com/ipdxco/unified-github-workflows/blob/main/scripts/copy-templates.sh"
  click renderScript "https://github.com/ipdxco/unified-github-workflows/blob/main/scripts/render-template.sh"
  click deleteScript "https://github.com/ipdxco/unified-github-workflows/blob/main/scripts/delete-templates.sh"
  click updateGo "https://github.com/ipdxco/unified-github-workflows/blob/main/scripts/update-go.sh"
  click closePRs "https://github.com/ipdxco/unified-github-workflows/blob/main/scripts/close-prs.sh"

  click templates "https://github.com/ipdxco/unified-github-workflows/tree/main/templates/"
  click defaults "https://github.com/ipdxco/unified-github-workflows/blob/main/defaults.yml"
  click versionData "https://github.com/ipdxco/unified-github-workflows/blob/main/templates/version.json"
  click changelog "https://github.com/ipdxco/unified-github-workflows/blob/main/CHANGELOG.md"
  click licenseAP "https://github.com/ipdxco/unified-github-workflows/tree/main/LICENSE-APACHE"
  click licenseMIT "https://github.com/ipdxco/unified-github-workflows/tree/main/LICENSE-MIT"

  classDef static fill:#9fcdff,stroke:#333,stroke-width:1px
  classDef action fill:#b3e6b3,stroke:#333,stroke-width:1px
  classDef workflow fill:#c2f0c2,stroke:#333,stroke-width:1px
  classDef api fill:#ffcc99,stroke:#333,stroke-width:1px
  classDef repo fill:#cccccc,stroke:#333,stroke-width:1px
  classDef runner fill:#d9d9ff,stroke:#333,stroke-width:1px
```
