GitHub Actions Workflows Documentation

This document describes all GitHub Actions workflows in the Dossier project, their purpose, and how they work.

Workflow Overview
1. Sign Workflow
2. Publish Packages Workflow
Best Practices
Troubleshooting

Workflow Overview

Workflow	File	Trigger	Purpose
CI	`ci.yml`	Pull request to main	Lint, build, test, and enforce version bumps on publishable packages
Sign	`sign.yml`	Manual	Test AWS KMS signing for dossier authentication
Publish Packages	`publish-packages.yml`	Push to main / Manual	Publish npm packages to the public npm registry

1. Sign Workflow (`sign.yml`)

Motivation

Dossiers support cryptographic signatures for authenticity verification. This workflow tests the AWS KMS (Key Management Service) signing infrastructure to ensure we can sign dossiers with production keys.

Why AWS KMS?

Hardware security module (HSM) backed keys
Never expose private keys
Audit trail for all signing operations
Enterprise-grade key management
Complies with security best practices

Trigger

Manual only via GitHub Actions UI:

Actions → sign → Run workflow

Flow

1. Checkout code
   ↓
2. Configure AWS credentials via OIDC
   - Uses GitHub OIDC to assume AWS IAM role
   - No static AWS credentials stored
   - Role: github-dossier-oidc (account: 942039714848)
   ↓
3. Create test artifact
   - Generate test file: "hello from github"
   ↓
4. Sign with AWS KMS
   - Calculate SHA-256 digest of artifact
   - Sign digest with KMS key: alias/dossier-official-prod
   - Algorithm: ECDSA_SHA_256
   - Output: signature.b64
   ↓
5. Export public key
   - Retrieve public key from KMS
   - Output: publickey.der
   ↓
6. Display results
   - Show file sizes for verification

Configuration

Environment Variables:

AWS_REGION: us-east-1 - AWS region for KMS
ROLE_ARN: arn:aws:iam::942039714848:role/github-dossier-oidc - IAM role to assume
KMS_KEY_ALIAS: alias/dossier-official-prod - Production signing key

Permissions:

id-token: write - Required for OIDC authentication
contents: read - Read repository code

Outputs

The workflow produces three files (not uploaded as artifacts currently):

artifact.bin - Test data signed
signature.b64 - Base64-encoded ECDSA signature
publickey.der - DER-encoded public key

Use Cases

Test signing infrastructure before releasing new dossiers
Verify AWS credentials and permissions are configured correctly
Generate signatures for high-risk dossiers
Export public key for signature verification setup

Future Enhancements

Upload signature and public key as workflow artifacts
Sign actual dossier files passed as input
Batch signing for multiple dossiers
Automatic signing on dossier updates
Integration with dossier publishing workflow

2. Publish Packages Workflow (`publish-packages.yml`)

Motivation

Automate the publishing of @ai-dossier/core, @ai-dossier/sched, @ai-dossier/cli, @ai-dossier/mcp-server, and @ai-dossier/worktree-pool npm packages to the public npm registry. This enables:

Continuous delivery: Automatic publishing on code changes
Version management: Centralized version bumping
Consistency: Same build process every time
Distribution: Easy installation for users via npm
Provenance: npm provenance attestation for supply chain security

Triggers

1. Automatic (Push to main)

Triggers when pushing to main branch AND changes affect:

cli/** - CLI package files
packages/core/** - Core package files
.github/workflows/publish-packages.yml - Workflow itself

2. Manual (workflow_dispatch)

Run manually via GitHub Actions UI with options:

Actions → Publish Packages to npm → Run workflow

Input: Version bump

skip (default) - Publish current version without bumping
patch - Bug fixes (0.1.0 → 0.1.1)
minor - New features (0.1.0 → 0.2.0)
major - Breaking changes (0.1.0 → 1.0.0)

Flow

1. Checkout code
   - Full repository checkout
   ↓
2. Setup Node.js (v20+)
   - Configure npm registry
   - Set @ai-dossier scope
   ↓
3. Install dependencies
   - npm install (all workspaces)
   ↓
4. Build @ai-dossier/core
   - Compile TypeScript → JavaScript
   - Generate type definitions
   ↓
5. Bump version (if requested)
   - Update version in packages/core/package.json
   - Update version in cli/package.json
   - Update version in mcp-server/package.json
   - Update CLI dependency on core
   ↓
6. Commit version bump (if bumped)
   - Commit updated package.json files
   - Push to main branch
   ↓
7. Publish @ai-dossier/core
   - Publish to https://registry.npmjs.org with --provenance
   - Includes: dist/, package.json, README
   ↓
8. Publish @ai-dossier/sched, @ai-dossier/cli, @ai-dossier/mcp-server, @ai-dossier/worktree-pool
   - Publish to https://registry.npmjs.org with --provenance
   - Each package checked by `scripts/publish-guard.mjs`: skipped if its version is already on
     npm from this commit or from identical release-relevant source; a version on npm built from
     different source is a collision — unaffected packages still publish (dependents of the
     colliding one are held), then `Fail on version collisions` fails the job (#826). A package
     the guard cannot decide (registry error, missing gitHead) is handled the same way, as
     `unavailable` — never skipped silently
   ↓
9. Create Git tag (if version bumped)
   - Tag format: v0.1.0, v0.2.0, etc.
   - Push tag to repository

Configuration

Permissions:

contents: write - Commit version bumps, create tags
id-token: write - npm provenance attestation

Node.js Setup:

Version: 22
Registry: https://registry.npmjs.org
Scope: @ai-dossier

Authentication:

Uses OIDC-based npm trusted publishing (no token secrets needed)
id-token: write permission enables provenance attestation

Outputs

Published Packages:

@ai-dossier/core → https://www.npmjs.com/package/@ai-dossier/core
@ai-dossier/sched → https://www.npmjs.com/package/@ai-dossier/sched
@ai-dossier/cli → https://www.npmjs.com/package/@ai-dossier/cli
@ai-dossier/mcp-server → https://www.npmjs.com/package/@ai-dossier/mcp-server
@ai-dossier/worktree-pool → https://www.npmjs.com/package/@ai-dossier/worktree-pool

Git Artifacts:

Version bump commit (if bumped)
Git tag (e.g., v0.2.0)

Use Cases

Automatic Publishing (Push-based)

# Make changes to CLI
vim cli/bin/ai-dossier

# Commit and push
git add cli/
git commit -m "fix: improve error messages"
git push origin main

# Workflow automatically publishes new version

Manual Release with Version Bump

Go to Actions → Publish Packages → Run workflow
Select minor for new feature release
Workflow bumps version, publishes, and tags

Testing Before Release

Ensure CI passes on the branch
Test installation on various platforms
Verify functionality via the publish pipeline’s verify job

Version Management

Automatic (workflow manages it):

Input: patch
Before: @ai-dossier/cli@0.1.0, @ai-dossier/core@1.0.0, @ai-dossier/mcp-server@0.1.0
After:  @ai-dossier/cli@0.1.1, @ai-dossier/core@1.0.1, @ai-dossier/mcp-server@0.1.1

- core, cli, and mcp-server bumped to the same version
- CLI dependency updated: "@ai-dossier/core": "^1.0.1"
- Commit: "chore: bump version to 0.1.1"
- Tag: v0.1.1

Why bump these packages together?

Keeps version numbers in sync
Simplifies dependency management
Clear release history
Matches semver expectations

Best Practices

For Workflow Maintainers

Test workflows in fork first before merging changes
Use path filters to prevent unnecessary workflow runs
Keep secrets secure - use OIDC, avoid static credentials
Document all changes in this file
Version workflows - commit history serves as changelog

For Contributors

Check workflow runs after pushing to ensure success
Review failed workflows and fix issues promptly
Don’t bypass workflows - they enforce quality and security
Understand triggers to avoid surprise publishes
Use manual triggers for testing

For Package Publishing

Always test locally first:

npm pack
npm install -g ./dossier-cli-0.1.0.tgz

Bump versions appropriately:
- patch - Bug fixes only
- minor - New features, backward compatible
- major - Breaking changes
Verify published packages:
```
npm info @ai-dossier/cli
```
Create GitHub releases for significant versions

Troubleshooting

Workflow Fails: “Package already exists”

Problem: Trying to publish a version that’s already published.

Solution: Bump the version first:

# Manual
cd cli
npm version patch
git push

# Or use workflow with version bump
Actions → Publish Packages → Run workflow → Select "patch"

Workflow Fails: ”@ version collision” / “Fail on version collisions”

Problem: The package’s version is already on npm but was published from a commit whose src//bin/ or @ai-dossier/* pins differ from this one — usually two PRs bumped to the same number and the other published first (#826), or an unbumped change merged under no-release-needed. Unaffected packages were published; this one (and its dependents) were not. Every publish run fails this way until the bump lands.

Solution: Open a follow-up PR bumping the named package past that version; its merge publishes the unreleased change:

cd cli && npm version patch --no-git-tag-version

Workflow Fails: “Publish guard could not decide” / “publish-guard () could not run”

Problem: The guard could not tell whether a package’s already-published version matches this commit — the registry answered something other than 200/404 after retries, the published version has no usable gitHead, or that gitHead could not be fetched. The package is recorded as unavailable: it is not published, its @ai-dossier/* dependents are held, unrelated packages still publish, and Fail on version collisions fails the job naming it. Nothing is skipped silently.

Solution: Follow the Fix: line in that package’s “Check if … needs publishing” log — re-run the workflow for a registry outage; bump the package’s version for a missing gitHead.

CI Fails: “Version-bump check FAILED”

Problem: The PR changes a publishable package’s src/ or bin/ but its package.json version still matches the base branch. After merge the publish workflow would find that version already on npm from different source and fail the run (version collision), leaving the change unreleased. The check also reports STALE (X is not above Y on the base-branch tip) when another PR bumped the package after your branch was cut — merge the base branch and bump above Y.

Solution: Bump the package’s version, or apply the no-release-needed label when the change needs no release:

cd cli
npm version patch --no-git-tag-version

Workflow Fails: “Permission denied” (Publishing)

Problem: GITHUB_TOKEN lacks package write permissions.

Solution:

Check workflow permissions in job definition
Ensure repository settings allow workflows to write packages:
- Settings → Actions → General → Workflow permissions
- Select “Read and write permissions”

Workflow Fails: AWS KMS “Access Denied”

Problem: GitHub OIDC role doesn’t have KMS permissions.

Solution: Contact AWS administrator to verify:

IAM role trust policy allows GitHub OIDC
Role has kms:Sign and kms:GetPublicKey permissions
KMS key policy allows the role

Workflow Doesn’t Trigger on Push

Problem: Push to main didn’t trigger publish workflow.

Possible causes:

Path filter: Changes not in cli/** or packages/core/**
- Check: git diff --name-only HEAD~1
Branch protection: Merge commits don’t trigger path-filtered workflows
- Use manual trigger instead
Workflow disabled: Check Actions settings

Solution: Trigger manually if needed:

Actions → Publish Packages → Run workflow

Published Package Can’t Be Installed

Problem: npm install @ai-dossier/cli fails with 404.

Solution: The packages are published to the public npm registry. Verify:

npm view @ai-dossier/cli

If the package was just published, it may take a few minutes to propagate.

Adding New Workflows

When adding a new workflow:

Create workflow file in .github/workflows/
Add documentation to this file:
- Motivation section
- Trigger conditions
- Flow diagram
- Configuration details
- Use cases
- Troubleshooting
Test thoroughly in a fork or feature branch
Update table of contents at the top of this document
Commit with descriptive message

Workflow Template

## N. Workflow Name (`filename.yml`)

### Motivation
Why does this workflow exist? What problem does it solve?

### Triggers
- Automatic: When does it run automatically?
- Manual: Can it be triggered manually?

### Flow
1. Step one
2. Step two
...

### Configuration
- Environment variables
- Secrets required
- Permissions needed

### Use Cases
- When to use this workflow
- Example scenarios

Publishing packages guide - Package publishing guide
GitHub Actions Docs
npm Provenance Docs
AWS KMS Docs

Last Updated: 2026-03-07 Maintained By: Dossier Core Team

Rendered from docs/contributing/workflows.md in the repository. Edit it there.

GitHub Actions Workflows Documentation

Table of Contents

Workflow Overview

1. Sign Workflow (sign.yml)

Motivation

Trigger

Flow

Configuration

Outputs

Use Cases

Future Enhancements

2. Publish Packages Workflow (publish-packages.yml)

Motivation

Triggers

Flow

Configuration

Outputs

Use Cases

Version Management

Best Practices

For Workflow Maintainers

For Contributors

For Package Publishing

Troubleshooting

Workflow Fails: “Package already exists”

Workflow Fails: ”@ version collision” / “Fail on version collisions”

Workflow Fails: “Publish guard could not decide” / “publish-guard () could not run”

CI Fails: “Version-bump check FAILED”

Workflow Fails: “Permission denied” (Publishing)

Workflow Fails: AWS KMS “Access Denied”

Workflow Doesn’t Trigger on Push

Published Package Can’t Be Installed

Adding New Workflows

Workflow Template

Related Documentation

1. Sign Workflow (`sign.yml`)

2. Publish Packages Workflow (`publish-packages.yml`)