@logickernel/agileflow 0.1.0

package/docs/gitlab-ci-template.md

@@ -0,0 +1,324 @@
+# GitLab CI Template Reference
+
+The AgileFlow GitLab CI template provides a streamlined, version-centric CI/CD pipeline that eliminates the complexity of traditional environment-based deployments.
+
+## Overview
+
+This template implements a 6-stage pipeline that focuses on version management rather than branch-based environment management. Every deployment, test, and operation is performed on well-identified versions, ensuring consistency and reliability across all environments.
+
+## Template Structure
+
+```yaml
+include:
+  - local: templates/AgileFlow.gitlab-ci.yml
+```
+
+## Pipeline Stages
+
+### 1. Version Stage
+The foundation of the AgileFlow approach. This stage automatically generates semantic versions and comprehensive release notes.
+
+**Job**: `agileflow`
+- **Image**: `registry.logickernel.com/kernel/agileflow:0.8.0`
+- **Script**: `agileflow gitlab-ci`
+- **Artifacts**: `VERSION` variable (dotenv report)
+
+**What it does**:
+- Analyzes commit history on the main branch
+- Calculates the next semantic version based on conventional commits
+- Generates comprehensive release notes
+- Creates and pushes version tags to the repository
+- Makes the `VERSION` variable available to all subsequent stages
+
+**Output**: The `VERSION` variable contains the generated semantic version (e.g., `v1.2.3`)
+
+### 2. Test Stage
+Runs tests against the source code before building artifacts.
+
+**Purpose**: Validate that the source code is ready for building and deployment
+**Input**: Source code and `VERSION` variable from the version stage
+**Output**: Test results and validation that the code meets quality standards
+
+**Example implementation**:
+```yaml
+test:
+  stage: test
+  script:
+    - npm test
+    - npm run lint
+  needs:
+    - agileflow
+```
+
+### 3. Build Stage
+Creates application artifacts and Docker images using the version from the version stage.
+
+**Purpose**: Build versioned artifacts that will be deployed across all environments
+**Input**: `VERSION` variable from the version stage
+**Output**: Versioned artifacts (e.g., `app:v1.2.3`, `frontend:v1.2.3`)
+
+**Example implementation**:
+```yaml
+build:
+  stage: build
+  script:
+    - docker build -t myapp:${VERSION} .
+    - docker push myapp:${VERSION}
+  needs:
+    - test
+```
+
+### 4. Deploy Stage
+Deploys the versioned artifacts to various environments.
+
+**Purpose**: Deploy the same version to staging, production, and other environments
+**Approach**: All environments receive identical versions, eliminating environment drift
+**Benefits**: Predictable deployments, simplified rollbacks, consistent behavior
+
+**Example implementation**:
+```yaml
+deploy-staging:
+  stage: deploy
+  script:
+    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
+  environment:
+    name: staging
+  needs:
+    - build
+
+deploy-production:
+  stage: deploy
+  script:
+    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
+  environment:
+    name: production
+  when: manual
+  needs:
+    - build
+```
+
+### 5. E2E Stage
+Validates the deployed version across all environments.
+
+**Purpose**: Run tests against the actual deployed version
+**Scope**: Integration tests, end-to-end tests, performance tests
+**Target**: Tests validate exactly what will run in production
+
+**Example implementation**:
+```yaml
+integration-tests:
+  stage: e2e
+  script:
+    - ./run-tests.sh --version ${VERSION}
+  needs:
+    - deploy-staging
+
+performance-tests:
+  stage: e2e
+  script:
+    - ./run-performance-tests.sh --version ${VERSION}
+  needs:
+    - deploy-staging
+```
+
+### 6. Clean Stage
+Cleanup temporary resources and artifacts.
+
+**Purpose**: Remove old Docker images, temporary files, and unnecessary artifacts
+**Maintenance**: Keep only necessary version artifacts
+**Optimization**: Reduce storage costs and improve pipeline performance
+
+**Example implementation**:
+```yaml
+cleanup:
+  stage: clean
+  script:
+    - docker image prune -f
+    - rm -rf /tmp/build-artifacts
+  when: always
+```
+
+## Key Benefits
+
+### Version Consistency
+- **Single Source of Truth**: All environments run identical versions
+- **No Environment Drift**: Staging and production are always in sync
+- **Predictable Deployments**: Every deployment uses a well-identified version
+
+### Simplified Operations
+- **Clear Version Tracking**: Easy to identify what's running where
+- **Simple Rollbacks**: Rollback to any previous version with confidence
+- **Reduced Complexity**: No need to manage multiple deployment branches
+
+### Enhanced Reliability
+- **Auditable Deployments**: Every deployment is tied to a specific version
+- **Consistent Testing**: Tests validate the exact version that will be deployed
+- **Improved Security**: Version-based deployments provide clear audit trails
+
+## Implementation Examples
+
+### Basic Implementation
+```yaml
+include:
+  - local: templates/AgileFlow.gitlab-ci.yml
+
+build:
+  stage: build
+  script:
+    - docker build -t myapp:${VERSION} .
+    - docker push myapp:${VERSION}
+  needs:
+    - agileflow
+
+deploy:
+  stage: deploy
+  script:
+    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
+  needs:
+    - build
+```
+
+### Advanced Implementation with Multiple Services
+```yaml
+include:
+  - local: templates/AgileFlow.gitlab-ci.yml
+
+build-backend:
+  stage: build
+  script:
+    - docker build -t backend:${VERSION} ./backend
+    - docker push backend:${VERSION}
+  needs:
+    - agileflow
+
+build-frontend:
+  stage: build
+  script:
+    - docker build -t frontend:${VERSION} ./frontend
+    - docker push frontend:${VERSION}
+  needs:
+    - agileflow
+
+deploy-staging:
+  stage: deploy
+  script:
+    - kubectl set image deployment/backend backend=backend:${VERSION}
+    - kubectl set image deployment/frontend frontend=frontend:${VERSION}
+  environment:
+    name: staging
+  needs:
+    - build-backend
+    - build-frontend
+
+deploy-production:
+  stage: deploy
+  script:
+    - kubectl set image deployment/backend backend=backend:${VERSION}
+    - kubectl set image deployment/frontend frontend=frontend:${VERSION}
+  environment:
+    name: production
+  when: manual
+  needs:
+    - build-backend
+    - build-frontend
+```
+
+## Best Practices
+
+### 1. Always Use the VERSION Variable
+```yaml
+# ✅ Good - Uses VERSION from AgileFlow
+- docker build -t myapp:${VERSION} .
+
+# ❌ Bad - Hardcoded or branch-based tagging
+- docker build -t myapp:latest .
+- docker build -t myapp:${CI_COMMIT_REF_SLUG} .
+```
+
+### 2. Proper Stage Dependencies
+```yaml
+# ✅ Good - Clear dependency chain
+deploy:
+  stage: deploy
+  needs:
+    - build
+
+# ❌ Bad - No dependencies specified
+deploy:
+  stage: deploy
+```
+
+### 3. Environment-Specific Deployments
+```yaml
+# ✅ Good - Same version, different environments
+deploy-staging:
+  environment:
+    name: staging
+
+deploy-production:
+  environment:
+    name: production
+  when: manual
+```
+
+### 4. Consistent Testing
+```yaml
+# ✅ Good - Test against deployed version
+test:
+  stage: test
+  script:
+    - ./run-tests.sh --version ${VERSION}
+  needs:
+    - deploy-staging
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**VERSION variable not available**
+- Ensure the `agileflow` job completed successfully
+- Check that the dotenv artifact is properly configured
+- Verify the job dependencies are set correctly
+
+**Build failures in later stages**
+- Check that the `VERSION` variable is being used correctly
+- Ensure all jobs have proper `needs` dependencies
+- Verify the artifact paths and variable names
+
+**Deployment inconsistencies**
+- Confirm that all deploy jobs use the same `${VERSION}` variable
+- Check that the same image tags are used across environments
+- Verify that the deployment scripts are identical
+
+### Debug Commands
+
+```yaml
+debug-version:
+  stage: build
+  script:
+    - echo "VERSION: ${VERSION}"
+    - echo "CI_COMMIT_REF_NAME: ${CI_COMMIT_REF_NAME}"
+    - echo "CI_COMMIT_SHA: ${CI_COMMIT_SHA}"
+  needs:
+    - agileflow
+```
+
+## Migration from Traditional CI/CD
+
+If you're currently using a traditional branch-based approach:
+
+1. **Include the template**: Add the include statement to your `.gitlab-ci.yml`
+2. **Update build jobs**: Modify build scripts to use `${VERSION}` instead of branch names
+3. **Consolidate deployments**: Deploy the same version to all environments
+4. **Update testing**: Ensure tests run against the deployed version
+5. **Remove branch logic**: Eliminate environment-specific branch handling
+
+## Support
+
+For issues or questions about the GitLab CI template:
+
+- Check the [main documentation](../README.md)
+- Review the [version-centric CI/CD approach](./version-centric-cicd.md)
+- Open an issue in the project repository
+- Join community discussions

package/docs/installation.md

@@ -0,0 +1,163 @@
+# Installation & Setup Guide
+
+This guide covers installing and setting up AgileFlow for different platforms and use cases.
+
+## Prerequisites
+
+Before installing AgileFlow, ensure you have:
+
+- **Git Repository**: A Git repository with GitLab CI/CD enabled
+- **GitLab Access**: Access to modify `.gitlab-ci.yml` files and CI/CD variables
+- **Basic Knowledge**: Understanding of Git, CI/CD, and Docker concepts
+
+## GitLab CI Installation
+
+### Step 1: Include the AgileFlow Template
+
+Add this line to the top of your `.gitlab-ci.yml` file:
+
+```yaml
+include:
+  - remote: https://code.logickernel.com/kernel/agileflow/-/raw/main/templates/AgileFlow.gitlab-ci.yml
+```
+
+### Step 2: Configure the AGILEFLOW_TOKEN
+
+AgileFlow needs a GitLab access token to create version tags via the API. Set this in your GitLab project's CI/CD variables:
+
+1. Go to your GitLab project
+2. Navigate to **Settings > CI/CD**
+3. Expand **Variables**
+4. Add the `AGILEFLOW_TOKEN` variable:
+
+| Variable | Value | Type | Protect | Mask |
+|----------|-------|------|---------|------|
+| `AGILEFLOW_TOKEN` | Your GitLab API token | Variable | Yes | No |
+
+#### Creating the AGILEFLOW_TOKEN
+
+You need a GitLab access token with API permissions. You can create either:
+
+**Option 1: Project Access Token (Recommended)**
+1. Go to your project's **Settings > Access Tokens**
+2. Create a new token with:
+   - **Name**: `AgileFlow Bot`
+   - **Description**: `Token for AgileFlow automatic versioning`
+   - **Role**: `maintainer` or higher
+   - **Scopes**: `api`
+3. Copy the generated token
+
+**Option 2: Personal Access Token**
+1. Go to your user **Settings > Access Tokens**
+2. Create a new token with:
+   - **Name**: `AgileFlow Bot`
+   - **Description**: `Token for AgileFlow automatic versioning`
+   - **Scopes**: `api`
+3. Copy the generated token
+
+### Step 3: Add Your First Job
+
+Below the include statement, add a simple build job to test the setup:
+
+```yaml
+build:
+  stage: build
+  script:
+    - echo "Building version ${VERSION}"
+    - docker build -t myapp:${VERSION} .
+    - docker push myapp:${VERSION}
+  needs:
+    - agileflow
+```
+
+### Step 4: Test the Installation
+
+1. Commit and push your changes:
+   ```bash
+   git add .gitlab-ci.yml
+   git commit -m "feat: add AgileFlow CI/CD pipeline"
+   git push
+   ```
+
+2. Check your GitLab CI pipeline - it should automatically start
+3. The `agileflow` job should complete successfully and generate a version
+4. Subsequent jobs should have access to the `${VERSION}` variable
+
+## How It Works
+
+AgileFlow uses a different approach than traditional CI/CD tools:
+
+### No Git Push Required
+- **AgileFlow does NOT push tags to your repository** using git commands
+- **Instead, it uses the GitLab API** to create tags remotely
+- **This eliminates the need** for job token permissions to push to the repository
+
+### Version Generation Process
+1. **Analyzes commit history** on the main branch
+2. **Calculates next semantic version** based on conventional commits
+3. **Creates version tag** via GitLab API (not git push)
+4. **Makes VERSION variable available** to all subsequent pipeline stages
+
+### Benefits of This Approach
+- **No repository write permissions** needed for CI/CD jobs
+- **More secure** - uses API tokens instead of git credentials
+- **Works with protected branches** without special permissions
+- **Consistent behavior** across all GitLab instances
+
+## Troubleshooting Installation
+
+### Common Issues
+
+#### AGILEFLOW_TOKEN Permission Errors
+
+**Problem**: Token permission denied errors.
+
+**Solutions**:
+- Ensure the token has `api` scope
+- Verify the token has `maintainer` role or higher
+- Check that the token hasn't expired
+- Confirm the token is for the correct project/user
+
+#### Template Include Fails
+
+**Problem**: The AgileFlow template include statement fails.
+
+**Solutions**:
+- Check network connectivity to `code.logickernel.com`
+- Verify the remote URL is accessible from your GitLab instance
+- Check firewall rules and network policies
+- Use a local copy of the template if remote access is restricted
+
+#### VERSION Variable Not Available
+
+**Problem**: The `${VERSION}` variable is not available in subsequent pipeline stages.
+
+**Solutions**:
+- Ensure the `agileflow` job completed successfully
+- Check that your jobs have `needs: - agileflow` dependency
+- Verify the dotenv artifact is properly configured
+- Check the `agileflow` job logs for errors
+
+### Debug Configuration
+
+Add a debug job to verify the setup:
+
+```yaml
+debug-version:
+  stage: build
+  script:
+    - echo "VERSION: ${VERSION}"
+    - echo "CI_COMMIT_REF_NAME: ${CI_COMMIT_REF_NAME}"
+    - echo "CI_COMMIT_SHA: ${CI_COMMIT_SHA}"
+  needs:
+    - agileflow
+```
+
+## Next Steps
+
+After successful installation:
+
+1. **Read the [Getting Started Guide](./getting-started.md)** for your first pipeline
+2. **Explore [Conventional Commits](./conventional-commits.md)** for proper commit formatting
+3. **Review [GitLab CI Template Reference](./gitlab-ci-template.md)** for advanced configuration
+4. **Check [Troubleshooting](./troubleshooting.md)** if you encounter issues