Collection of GitHub Actions for flxbl.io / sfops. Each action is a standalone GitHub repository managed as a git submodule.

This is a monorepo-style parent repository that manages multiple GitHub Actions as git submodules. Each action lives in its own repository under the flxbl-io organization and is linked here for unified development.

flxbl-io/flxbl-actions/           # Parent repo (this repository)
├── build-domain/                 # Submodule → flxbl-io/build-domain
├── release-domain/               # Submodule → flxbl-io/release-domain
├── get-github-token/             # Submodule → flxbl-io/get-github-token
├── auth-environment-with-lock/   # Submodule → flxbl-io/auth-environment-with-lock
├── ...                           # Other action submodules
├── scripts/
│   ├── sync.js                   # Auto-sync script
│   └── detect-sfp-stack.sh       # Local testing utility
├── .github/
│   ├── workflows/                # CI/CD for actions
│   └── workflow-templates/       # Templates for new actions
└── package.json                  # NPM scripts

# Clone with all submodules
git clone --recurse-submodules https://github.com/flxbl-io/flxbl-actions.git
cd flxbl-actions

# Or if already cloned without submodules
npm run setup

# 1. Navigate to the action
cd get-github-token

# 2. Make your changes
vim src/index.ts

# 3. Build and test
npm install
npm run build
npm test

# 4. Sync everything (from anywhere in the repo)
cd ..
npm run sync "feat: add timeout configuration"

The sync script (scripts/sync.js) automates the multi-repo workflow:

1. Auto-detects which actions have uncommitted changes or unpushed commits
2. Commits changes in each modified action submodule
3. Pushes each action to its own GitHub repository
4. Updates the parent repo to point to the new submodule commits
5. Pushes the parent repo

You can run it from the root directory (syncs all changed actions) or from within an action directory (syncs only that action).

# From root - syncs all changed actions
npm run sync "fix: handle null response"

# From action directory - syncs only current action
cd lock-environment
npm run sync "feat: add retry logic"

# See which submodules have changes
npm run status

# Output shows:
#  + prefix = has new commits not tracked by parent
#  - prefix = has commits missing (needs update)
#  no prefix = up to date

# Update all submodules to latest remote commits
npm run update

Each action follows this standard structure:

{action-name}/
├── action.yml              # Action metadata (required)
├── src/                    # Source code (Node.js actions)
│   ├── index.ts            # Main entry point
│   ├── cleanup.ts          # Post step (if applicable)
│   └── __tests__/          # Unit tests
├── dist/                   # Compiled output (committed)
│   ├── index.js
│   └── cleanup.js          # If post step exists
├── package.json
├── tsconfig.json
├── jest.config.js
├── README.md
├── CHANGELOG.md
└── LICENSE

Node.js Actions (preferred for complex logic):

• Built with TypeScript and @vercel/ncc
• Can have post steps for cleanup (e.g., auto-unlock)
• Use @actions/core for inputs/outputs/state

Composite Actions (for simple CLI wrappers):

• Direct shell commands in action.yml
• No post step support
• Simpler but less flexible

Releases are automated using release-please in each action repository.

1. Use conventional commits:

   git commit -m "feat: add new feature"      # → minor version bump
   git commit -m "fix: bug fix"               # → patch version bump
   git commit -m "feat!: breaking change"     # → major version bump

2. On push to main: release-please creates/updates a Release PR

3. Merge the Release PR: creates GitHub Release and updates version tags (v1, v1.0, v1.0.0)

The .github/workflows/ directory contains reusable workflows that individual actions can call:

Actions call the shared CI workflow:

# In action's .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  ci:
    uses: flxbl-io/flxbl-actions/.github/workflows/ci.yml@main
    with:
      action-type: node  # or 'composite'

The CI workflow:

• Installs dependencies
• Runs tests
• Builds the action
• Verifies dist/ is up to date
• Validates action.yml syntax

Actions call the shared release workflow:

# In action's .github/workflows/release.yml
name: Release
on:
  push:
    branches: [main]
jobs:
  release:
    uses: flxbl-io/flxbl-actions/.github/workflows/release.yml@main
    secrets:
      GHA_TOKEN: ${{ secrets.GHA_TOKEN }}

1. Create the action repository under flxbl-io
2. Use workflow templates from .github/workflow-templates/
3. Add as submodule:

   git submodule add https://github.com/flxbl-io/new-action.git new-action

4. Follow naming convention: {verb}-{noun} (e.g., get-github-token, not get-github-token-action)

Templates for new actions are in .github/workflow-templates/:

Proprietary - flxbl.io