diff --git a/.github/README.md b/.github/README.md new file mode 100644 index 0000000..e5e4723 --- /dev/null +++ b/.github/README.md @@ -0,0 +1,178 @@ +# GitHub Actions CI/CD Pipeline + +This repository uses GitHub Actions for continuous integration and deployment. The pipeline automatically builds, tests, and publishes the OSLC components. + +## Workflow Overview + +The CI/CD pipeline consists of several jobs that run automatically: + +### 1. Test Job +- **Trigger**: On every push and pull request +- **Actions**: + - Installs dependencies for both components + - Runs tests (if available) + - Builds both components to verify they compile correctly + - Validates the build artifacts + +### 2. Build and Publish Job +- **Trigger**: On push to `main` branch +- **Actions**: + - Builds both `@oslc/postmessage-helper` and `@oslc/selection-webcomponent` + - Publishes packages to GitHub NPM registry + - Skips publishing if version already exists + - Uploads build artifacts for other jobs + +### 3. Deploy Demo Job +- **Trigger**: On push to `main` branch (after successful build) +- **Actions**: + - Builds the demo with production components + - Deploys to GitHub Pages + - Creates version information for deployment tracking + +### 4. Publish Release Job +- **Trigger**: On GitHub release creation +- **Actions**: + - Updates package versions to match release tag + - Publishes versioned packages with `latest` tag + - Creates release artifacts archive + +## Package Registry + +Packages are published to the GitHub NPM registry: +- **Registry URL**: `https://npm.pkg.github.com` +- **Packages**: + - `@oslc/postmessage-helper` + - `@oslc/selection-webcomponent` + +## GitHub Pages Deployment + +The demo is automatically deployed to GitHub Pages: +- **URL**: `https://OSLC.github.io/olsc-selection-utils/` +- **Source**: Built from `src/oslc-selection-demo/` with production components +- **Updates**: Automatically on every push to `main` + +## Using the Published Packages + +### Install from GitHub NPM Registry + +First, configure npm to use the GitHub registry for `@oslc` packages: + +```bash +npm config set @oslc:registry https://npm.pkg.github.com +``` + +Then install the packages: + +```bash +npm install @oslc/postmessage-helper +npm install @oslc/selection-webcomponent +``` + +### Authentication + +To install packages from the GitHub registry, you need to authenticate: + +```bash +npm login --registry=https://npm.pkg.github.com +``` + +Or use a `.npmrc` file: + +``` +@oslc:registry=https://npm.pkg.github.com +//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN +``` + +## Environment Variables + +The workflow uses these environment variables: + +- `NODE_VERSION`: Node.js version (currently 18) +- `REGISTRY_URL`: GitHub NPM registry URL +- `GITHUB_TOKEN`: Automatically provided by GitHub Actions + +## Permissions + +The workflow requires these permissions: + +- `contents: read` - Read repository contents +- `packages: write` - Publish to GitHub NPM registry +- `pages: write` - Deploy to GitHub Pages +- `id-token: write` - For GitHub Pages deployment + +## Manual Deployment + +To manually deploy or test locally: + +### Build Components +```bash +# Windows +.\scripts\build-components.ps1 + +# Linux/macOS +./scripts/build-components.sh +``` + +### Run Demo Locally +```bash +cd src/oslc-selection-demo +python -m http.server 8080 +# or +npx serve . +``` + +### Publish to Registry (with proper authentication) +```bash +cd src/oslc-postmessage-helper +npm publish --registry=https://npm.pkg.github.com + +cd ../oslc-selection-webcomponent +npm publish --registry=https://npm.pkg.github.com +``` + +## Release Process + +To create a new release: + +1. Update version numbers in both `package.json` files +2. Commit and push changes +3. Create a GitHub release with a tag like `v1.0.1` +4. The workflow will automatically publish the versioned packages + +## Troubleshooting + +### Common Issues + +1. **Authentication failures**: Ensure `GITHUB_TOKEN` has package write permissions +2. **Build failures**: Check that all dependencies are properly specified +3. **Pages deployment issues**: Verify the demo builds correctly locally first + +### Debug Information + +Each job provides detailed logs. Check the Actions tab for: +- Build output +- Test results +- Publishing status +- Deployment logs + +### Local Testing + +Before pushing, test the build locally: + +```bash +# Test the build process +npm ci +npm run build +npm run test + +# Test the demo +cd src/oslc-selection-demo +# Verify all files are present and demo works +``` + +## Security + +- Secrets are managed through GitHub Actions +- Package registry uses GitHub token authentication +- No sensitive information is stored in the repository +- All builds run in isolated environments diff --git a/.github/pages.yml b/.github/pages.yml new file mode 100644 index 0000000..e172927 --- /dev/null +++ b/.github/pages.yml @@ -0,0 +1,32 @@ +# GitHub Pages configuration +# This file enables GitHub Pages deployment for the OSLC Selection Utils demo + +# Use GitHub Actions for deployment +source: + type: github-actions + +# Deployment configuration +deployment: + # Use the demo folder as the root + source_folder: src/oslc-selection-demo + + # Custom domain (optional - uncomment and modify if you have one) + # custom_domain: your-domain.com + +# Build configuration +build: + # Include vendor directory with built components + include: + - vendor/ + - "*.html" + - "*.js" + - "*.css" + - "*.json" + + # Exclude development files + exclude: + - node_modules/ + - "*.md" + - "*.log" + - ".DS_Store" + - "Thumbs.db" diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml new file mode 100644 index 0000000..4622f94 --- /dev/null +++ b/.github/workflows/ci-cd.yml @@ -0,0 +1,289 @@ +name: CI/CD Pipeline + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main ] + release: + types: [ published ] + +env: + NODE_VERSION: '22' + REGISTRY_URL: 'https://npm.pkg.github.com' + +jobs: + test: + name: Test Components + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: ${{ env.NODE_VERSION }} + cache: 'npm' + + - name: Install dependencies + run: npm install + + - name: Run tests for postmessage-helper + run: npm run test --workspace=@oslc/postmessage-helper || echo "No tests configured" + + - name: Build postmessage-helper + run: npm run build --workspace=@oslc/postmessage-helper + + - name: Run tests for selection-webcomponent + run: npm run test --workspace=@oslc/selection-webcomponent || echo "No tests configured" + + - name: Build selection-webcomponent + run: npm run build --workspace=@oslc/selection-webcomponent + + build-and-publish: + name: Build and Publish to GitHub Registry + needs: test + runs-on: ubuntu-latest + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + permissions: + contents: read + packages: write + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: ${{ env.NODE_VERSION }} + registry-url: ${{ env.REGISTRY_URL }} + cache: 'npm' + + - name: Configure npm for GitHub Registry + run: | + echo "@oslc:registry=${{ env.REGISTRY_URL }}" >> ~/.npmrc + echo "${{ env.REGISTRY_URL }}/:_authToken=${{ secrets.GITHUB_TOKEN }}" >> ~/.npmrc + + - name: Update package.json repository URLs + run: | + # Update postmessage-helper package.json + cd src/oslc-postmessage-helper + npm pkg set repository.url="git+https://github.com/${{ github.repository }}.git" + npm pkg set repository.directory="src/oslc-postmessage-helper" + npm pkg set publishConfig.registry="${{ env.REGISTRY_URL }}" + + # Update selection-webcomponent package.json + cd ../oslc-selection-webcomponent + npm pkg set repository.url="git+https://github.com/${{ github.repository }}.git" + npm pkg set repository.directory="src/oslc-selection-webcomponent" + npm pkg set publishConfig.registry="${{ env.REGISTRY_URL }}" + + - name: Install dependencies + run: npm install + + - name: Build and publish postmessage-helper + run: | + npm run build --workspace=@oslc/postmessage-helper + cd src/oslc-postmessage-helper + npm pack + + # Check if version exists before publishing + VERSION=$(npm pkg get version | tr -d '"') + if npm view @oslc/postmessage-helper@$VERSION --registry=${{ env.REGISTRY_URL }} 2>/dev/null; then + echo "Version $VERSION already exists, skipping publish" + else + npm publish + fi + env: + NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Build and publish selection-webcomponent + run: | + npm run build --workspace=@oslc/selection-webcomponent + cd src/oslc-selection-webcomponent + npm pack + + # Check if version exists before publishing + VERSION=$(npm pkg get version | tr -d '"') + if npm view @oslc/selection-webcomponent@$VERSION --registry=${{ env.REGISTRY_URL }} 2>/dev/null; then + echo "Version $VERSION already exists, skipping publish" + else + npm publish + fi + env: + NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Upload build artifacts + uses: actions/upload-artifact@v4 + with: + name: built-packages + path: | + src/oslc-postmessage-helper/dist/ + src/oslc-selection-webcomponent/dist/ + src/oslc-postmessage-helper/*.tgz + src/oslc-selection-webcomponent/*.tgz + + deploy-demo: + name: Deploy Demo to GitHub Pages + needs: [test, build-and-publish] + runs-on: ubuntu-latest + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + permissions: + contents: read + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: ${{ env.NODE_VERSION }} + cache: 'npm' + + - name: Install dependencies + run: npm install + + - name: Build components for demo + run: | + # Build both components using workspace commands + npm run build --workspace=@oslc/postmessage-helper + npm run build --workspace=@oslc/selection-webcomponent + + # Copy built components to demo vendor folder + mkdir -p src/oslc-selection-demo/vendor/@oslc/oslc-postmessage-helper + mkdir -p src/oslc-selection-demo/vendor/@oslc/oslc-selection-webcomponent + + cp -r src/oslc-postmessage-helper/dist/* src/oslc-selection-demo/vendor/@oslc/oslc-postmessage-helper/ + cp -r src/oslc-selection-webcomponent/dist/* src/oslc-selection-demo/vendor/@oslc/oslc-selection-webcomponent/ + + - name: Create deployment version info + run: | + cd src/oslc-selection-demo + cat > version.json << EOF + { + "version": "$(date -u +%Y%m%d-%H%M%S)", + "commit": "${{ github.sha }}", + "branch": "${{ github.ref_name }}", + "buildTime": "$(date -u --iso-8601=seconds)", + "components": { + "postmessage-helper": "$(cd ../oslc-postmessage-helper && npm pkg get version | tr -d '\"')", + "selection-webcomponent": "$(cd ../oslc-selection-webcomponent && npm pkg get version | tr -d '\"')" + } + } + EOF + + - name: Create index page with build info + run: | + cd src/oslc-selection-demo + # Add build info to the HTML + sed -i 's|
+ Experience the OSLC Selection WebComponent with full styling capabilities. This demo showcases + both the functional OSLC integration and the comprehensive theming system using CSS custom properties. +
++ Click the button below to experience OSLC resource selection. This demo simulates + the selection process and displays the results. +
+ + +Use the selection button above to choose OSLC resources. Selected items will appear here.
+The OSLC Selection WebComponent supports extensive styling through CSS custom properties. Here are various pre-built themes:
+ +After building, refresh this page to see the production components in action with full OSLC integration.
+