Skip to content

Getting Started with Deepworks Actions

This guide will help you understand and implement Deepworks GitHub Actions workflows in your repositories.

Architecture Overview

Deepworks Actions use a six-layer FCM architecture with a bridge system:

  • Axioms: Core capabilities defined as Formal Conceptual Models
  • Generated Actions: GitHub-compatible interfaces automatically generated from axioms
  • Bridge System: Ensures consistency between pure definitions and GitHub requirements

Overview

Deepworks Actions provide a suite of reusable workflows for:

  • Documentation management with MkDocs
  • Release management and versioning
  • Changelog automation
  • Repository standardization
  • Git operations (branches, tags, commits)
  • Version calculation and updating

Core Workflows

MkDocs GitHub Pages

Handles documentation deployment:

name: Documentation
jobs:
  docs:
    uses: deepworks-net/github.actions/.github/workflows/mkdocs-gh-pages.yml@main

Release Management

Manages releases and versioning:

name: Release
jobs:
  release:
    uses: deepworks-net/github.actions/.github/workflows/release-drafter.yml@main

Changelog Updates

Automates changelog maintenance:

name: Changelog
jobs:
  changelog:
    uses: deepworks-net/github.actions/.github/workflows/update-changelog.yml@main

Workflow Integration Map

graph TD
    A[New PR] --> B{Merged to Develop}
    B --> C[Update Changelog]
    B --> D[Update Draft Release]
    C --> E[Prepare Release]
    D --> E
    E --> F[Create Release PR]
    F --> G[Merge to Main]
    G --> H[Publish Release]

Setup Instructions

Using Generated Actions

  1. Repository Configuration
# .github/workflows/docs.yml
name: Documentation
on:
  push:
    branches:
      - main

jobs:
  docs:
    uses: deepworks-net/github.actions/.github/workflows/mkdocs-gh-pages.yml@main
  1. Using Core Actions
# Using generated tag operations
- uses: deepworks-net/github.actions/actions/core/tag-operations@main
  with:
    action: create
    tag_name: v1.0.0
    message: "Release version 1.0.0"
  1. Required Files
  2. mkdocs.yml for documentation
  3. CHANGELOG.md for release notes

  4. .github/release-drafter.yml for release configuration

  5. Repository Settings

  6. Enable GitHub Pages
  7. Set appropriate branch protections
  8. Configure required status checks

Working with FCM Architecture

  1. Understanding Axioms: Browse axioms/ to see available capabilities
  2. Never Edit Actions Directly: All actions in actions/ are generated
  3. Modify Through FCMs: Edit capability definitions in axioms/ directory
  4. Regenerate When Needed: Use bridge tools to update generated actions

Basic Usage

Documentation Updates

  1. Make changes to docs
  2. Push to main
  3. Workflow automatically deploys

Release Process

  1. Create changes in feature branch
  2. Merge PR to develop
  3. Changelog updates automatically
  4. Draft release updates
  5. Prepare release when ready
  6. Merge release PR
  7. Final release publishes

Advanced Configuration

Custom MkDocs Settings

jobs:
  docs:
    uses: deepworks-net/github.actions/.github/workflows/mkdocs-gh-pages.yml@main
    with:
      python-version: '3.11'
      requirements-file: 'docs/requirements.txt'

Release Configuration

jobs:
  release:
    uses: deepworks-net/github.actions/.github/workflows/release-drafter.yml@main
    with:
      tag-name: 'v1.0.0'

Next Steps

Common Issues

  1. Documentation Not Deploying
  2. Check GitHub Pages settings
  3. Verify mkdocs.yml configuration

  4. Review workflow permissions

  5. Release Draft Not Updating

  6. Check release-drafter.yml configuration
  7. Verify branch names

  8. Review GitHub token permissions

  9. Changelog Not Updating

  10. Ensure PR merged to correct branch
  11. Check file paths
  12. Verify workflow permissions

Getting Help

  • Open an issue on GitHub
  • Check existing documentation
  • Review workflow run logs