Skip to main content

​
CI/CD Pipeline Integration

This page describes how teams typically wire fastskill into automation: detect changes, package ZIPs, and optionally publish to a registry. Publishing requires a FastSkill build compiled with the registry-publish feature.

​
What you can automate

  • Automatic Change Detection: Detect which skills have changed using git diff or file hashing
  • Version Bumping: Automatically increment semantic versions (major, minor, patch)
  • Artifact Creation: Package skills into ZIP files with metadata and checksums
  • Optional Registry Publishing: Send packaged artifacts to a registry API or local handoff directory
  • Registry Index Management: Maintain a registry index for skill distribution in operator builds

​
Change Detection Strategies

​
Git-based Detection

Use git diff to detect changed skill directories. Common in hosted git runners: 
fastskill package --git-diff HEAD~1 HEAD --auto-bump --output ./artifacts
Advantages:
  • Fast and efficient
  • Works well in CI/CD environments
  • Can compare any two git references (commits, tags, branches)
Use Cases:
  • GitHub Actions workflows
  • GitLab CI pipelines
  • Any git-based CI/CD system

​
Hash-based Detection

Use file hashing to detect changes when you prefer not to rely on git metadata: 
fastskill package --detect-changes --auto-bump --output ./artifacts
Advantages:
  • Works without git repository
  • Detects any file changes
  • Maintains build cache for efficiency
Typical uses:
  • Sandboxes without full git history
  • Incremental packaging on a workstation

​
Version Bumping Strategies

​
Explicit Bump Type

Specify the bump type explicitly: 
# Major version (breaking changes)
fastskill package --detect-changes --bump major

# Minor version (new features)
fastskill package --detect-changes --bump minor

# Patch version (bug fixes)
fastskill package --detect-changes --bump patch

​
Auto-detect Bump Type

Let FastSkill determine the bump type (currently defaults to patch): 
fastskill package --detect-changes --auto-bump
Future versions may analyze commit messages or change types to determine appropriate bump level.

​
Complete Workflow Examples

​
Local packaging loop

fastskill package --detect-changes --auto-bump --output ./artifacts
fastskill publish --registry official   # requires registry-publish; or use --api-url / --local-dir

​
Example: hosted runner (outline)

  1. Check out your repository with enough history for fastskill package --git-diff <from> <to>.
  2. Install the fastskill binary using the same method you use on laptops. Use an operator build with registry-publish if the job publishes artifacts.
  3. Restore secrets for registries (FASTSKILL_API_URL, tokens, cloud credentials) as environment variables.
  4. Run fastskill package … then fastskill publish … with the flags from package and publish.
# Illustrative fragment only — adjust names, triggers, and secrets to your org
jobs:
  skills:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - name: Install FastSkill CLI
        run: |
          # Use your standard install path (release tarball, package, or internal mirror)
          fastskill -V
      - name: Package changed skills
        run: fastskill package --git-diff HEAD~1 HEAD --auto-bump --output ./artifacts
      - name: Publish
        run: fastskill publish --local-dir ./upload
        env:
          FASTSKILL_API_URL: ${{ secrets.FASTSKILL_API_URL }}

​
Other runners

GitLab CI, Jenkins, Buildkite, and others follow the same outline: put fastskill on PATH, check out sources, run package, then run publish only in jobs that use a registry-publish build. Copy the CLI arguments from fastskill package --help and fastskill publish --help rather than relying on historical workflow snippets. 
// Jenkins-style pseudocode — replace install and credentials with yours
pipeline {
    agent any
    
    environment {
        AWS_ACCESS_KEY_ID = credentials('aws-access-key-id')
        AWS_SECRET_ACCESS_KEY = credentials('aws-secret-access-key')
    }
    
    stages {
        stage('Package') {
            steps {
                sh '''
                    fastskill package \
                        --git-diff HEAD~1 HEAD \
                        --auto-bump \
                        --output ./artifacts
                '''
            }
        }
        
        stage('Publish') {
            steps {
                sh '''
                    fastskill publish \
                        --artifacts ./artifacts \
                        --api-url "${FASTSKILL_API_URL}"
                '''
            }
        }
    }
}

​
Configuration Best Practices

​
Environment Variables

Store sensitive credentials as environment variables or secrets: 
# AWS S3
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret

# Blob storage base URL
export BLOB_BASE_URL=https://blob.example.com/skills

​
Configuration Files

Use .fastskill/publish.toml for non-sensitive configuration: 
[blob_storage]
type = "s3"
bucket = "skills-registry"
region = "us-east-1"
# Credentials from environment variables

[registry]
git_url = "https://github.com/GoFastSkill/skill-registry.git"
branch = "main"
blob_base_url = "https://blob.example.com/skills"

​
Build Cache

The build cache (.fastskill/build-cache.json) can be persisted between pipeline runs if you want faster packaging. Treat it as a machine-local artifact: refresh or delete it when packaging results look wrong.

​
Troubleshooting

​
No Skills Detected

If no skills are detected for packaging:
  1. Check that skills directory exists and contains SKILL.md files
  2. Verify git diff is working: git diff HEAD~1 HEAD --name-only
  3. Check build cache for stale entries
  4. Use --force to package all skills regardless of changes

​
Version Bumping Issues

If version bumping fails:
  1. Ensure skill-project.toml exists or can be created
  2. Check that version format is valid semver (e.g., “1.2.3”)
  3. Verify write permissions for skill-project.toml

​
Blob Storage Upload Failures

If uploads fail:
  1. Verify credentials are correct
  2. Check network connectivity to storage endpoint
  3. Ensure bucket/container exists and is accessible
  4. Verify IAM permissions for S3 buckets

​
Registry Index Issues

If registry index operations fail:
  1. Ensure git repository is accessible
  2. Check git credentials and permissions
  3. Verify registry path exists and is writable
  4. Ensure blob base URL is correct

​
See Also