Seal GitHub App for Change Control

Prepare Your Seal Environment

First, configure your Seal account with the necessary templates and permissions:

1. Create a Change Control Template in Seal (Required for PR Sync):
   • Required Fields: Add fields corresponding to the data synced from GitHub. Recommended names:
     • Description of Change (Text/Rich Text)
     • PR Number (Text or Number)
     • PR Link (Text/URL)
     • Repository Name (Text)
     • Repository ID (Text)
     • PR Title (Text)
   • Required Status Tags (for Monitoring): If using the automated PR approval/rejection monitoring, configure your template's workflow status states to include Status Tags named exactly:
     • Approved
     • Rejected
2. Create an Issue Tracking Template in Seal (Optional - Required for Issue Sync):
   • Required Fields: Add fields corresponding to the data synced from GitHub Issues. Field names **must match exactly**:
     • GitHub Issue Number (Text or Number)
     • GitHub Issue Title (Text)
     • Issue Description (Text/Rich Text)
     • GitHub Issue Link (Text/URL)
     • GitHub Issue Labels (Text)
     • Repository Name (Text)
     • GitHub Status (**Single Select** Type): Must have options with these exact values:
       • Unresolved
       • Resolved in Main
       • Untagged
3. Entity Lookup Strategy (Important):
   • The app primarily finds existing entities by searching the main **Entity Title** for specific markers:
     • PRs: `(#PR_NUMBER)` (e.g., `My Feature (#123)`)
     • Issues: `(REPO_NAME#ISSUE_NUMBER)` (e.g., `Fix Login Bug (my-repo#45)`)
4. Publish both templates - Templates must be published to be accessible via API.
5. Generate a Seal API token:
   • Go to Settings → Developer settings → Personal Access Tokens
   • Click "Create New Token" and select your organization as the resource owner
   • Copy and securely store the generated token
6. Collect Seal IDs & URLs:
   • Copy the **Template ID** for each template from its URL.
   • Note your Seal **Organization ID** and **Organization Name** (from URL/Settings).
   • Note your Seal **Platform Base URL** (e.g., us.platform.seal.run) and **API Base URL** (e.g., https://us.backend.seal.run/api/).

Install the GitHub App

1. Go to the GitHub Marketplace:
   • Visit Seal Change Control on GitHub
   • Click the "Install" button
2. Choose Installation Scope:
   • Select "All repositories" or choose specific repositories
   • For a production setup, we recommend starting with a single test repository
3. Authorize the Installation with your GitHub credentials
4. Verify Installation in your GitHub organization settings under "GitHub Apps"

Configure GitHub Secrets & Repository File

Set up the necessary secrets and configuration file in your GitHub organization/repository:

1. Configure GitHub Secrets: Add the following secrets at the Organization or Repository level (Repository secrets override Org secrets):
   • SEAL_API_TOKEN: Your Seal API token generated earlier.
2. Create Configuration File: Create .github/seal-change-control-config.yml in your repository.
3. Add your configuration using the template below (replace placeholders):

# .github/seal-change-control-config.yml

# --- Core Settings (Required) ---
sealTemplateId: "YOUR_SEAL_CHANGE_CONTROL_TEMPLATE_ID"
sealApiBaseUrl: "https://YOUR_SEAL_API_BASE_URL/" # Must end with /
platformBaseUrl: "YOUR_SEAL_PLATFORM_BASE_URL" # e.g., us.platform.seal.run

# --- Branch Filtering (Required for PR Sync) ---
sourceBranchRegex: "^YOUR_FEATURE_BRANCH_PATTERN$" # e.g., "^feature/" or "^(feature/|hotfix/|chore/)" for multiple
targetBranchRegex: "^YOUR_RELEASE_BRANCH_PATTERN$" # e.g., "^main$" or "^(main|develop|release/.*)$" for multiple

# --- Issue Tracking (Optional - Required for Issue Sync) ---
issueSyncTemplateId: "YOUR_SEAL_ISSUE_TEMPLATE_ID" # Required if syncing issues
issueLabelRegex: "(bug|defect|seal)" # Regex for labels to trigger issue sync

# --- User Feedback Configuration (Optional) ---
# --- Testing ---
isTesting: true # Set true for detailed logs during setup, false for production

Optional: Setup Automated Workflows via GitHub Actions

Enhance your integration by adding GitHub Actions for tasks like snapshotting code or uploading build artifacts directly to Seal.

Example 1: Codebase Snapshot using Docker Action

This action creates a ZIP archive of your PR's codebase and uploads it to a specified field in the corresponding Seal entity.

1. Add Field in Seal: Add a "Reference" type field (e.g., Code Snapshot) to your Seal Change Control template. Enable "Allow Multiple" if desired.
2. Create Workflow File: Add this workflow to .github/workflows/codebase_snapshot.yml.
3. Configure Secrets: Ensure the SEAL_API_TOKEN secret is configured in GitHub.
4. (Optional) Create File Type in Seal: You might need to create a file type (e.g., GitHub-Artifacts) in Seal Admin settings if the action specifies one (seal_file_type_title).

# .github/workflows/codebase_snapshot.yml
name: Codebase Snapshot via Image

on:
  pull_request:
    # Trigger on PRs targeting specific branches, e.g., release branches
    branches:
      - 'r[0-9]+.x' # Release branches like r1.x, r2.x
      - 'feature/*' # All feature branches
      - 'main' # Main branch
      - 'develop' # Develop branch

# Required permissions for the action
permissions:
  contents: read
  pull-requests: read
  packages: read # Needed to read docker image from GHCR

jobs:
  codebase_snapshot_via_image:
    runs-on: ubuntu-latest
    steps:
      # Step 1: Checkout code (needed for the action to archive)
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Recommended for accurate snapshot

      # Step 2: Run the Docker container action
      - name: Create and Upload Seal Snapshot
        # Use the specific Docker image from GHCR
        uses: docker://ghcr.io/opvia/codebase-snapshot-action:latest # Use a specific version tag in production
        with:
          # Seal API Configuration
          seal_api_token: ${{ secrets.SEAL_API_TOKEN }}
          seal_api_base_url: 'https://YOUR_SEAL_API_BASE_URL/' # e.g., https://us.backend.seal.run/api/
          
          # Seal Template and Field Configuration
          seal_template_id: 'YOUR_SEAL_CHANGE_CONTROL_TEMPLATE_ID' # From Step 1
          seal_snapshot_field_name: 'Code Snapshot' # Field created in Seal
          seal_file_type_title: 'GitHub-Artifacts' # Optional: Categorizes file in Seal

          # Snapshot Configuration
          exclude_patterns: '.git/* node_modules/* dist/* build/*' # Space-separated
          archive_type: 'zip' # Or 'tar.gz'

Example 2: Upload Release Artifacts using Repository Action

This action uploads specified build artifacts (like binaries, documentation PDFs) from your workflow run to a Seal entity.

1. Add Field in Seal: Add a "Reference" type field (e.g., Release Artifact(s)) to your Seal Change Control template. Enable "Allow Multiple".
2. Create Workflow File: Add this workflow to .github/workflows/upload_artifacts.yml (or integrate steps into your existing build/release workflow).
3. Configure Secrets: Ensure the SEAL_API_TOKEN secret is configured in GitHub.
4. (Optional) Create File Type in Seal: Define a relevant file type (e.g., GitHub-Artifacts) in Seal Admin settings if using seal_file_type_title.

# .github/workflows/upload_artifacts.yml
name: Upload Release Artifacts to Seal

on:
  pull_request: # Or on: release, workflow_dispatch, etc.
    branches:
      - 'r[0-9]+.x' # Release branches like r1.x, r2.x
      - 'feature/*' # All feature branches
      - 'main' # Main branch
      - 'develop' # Develop branch

# Required permissions
permissions:
  contents: read
  pull-requests: read

jobs:
  build_and_upload_artifacts:
    runs-on: ubuntu-latest
    steps:
      # Step 1: Checkout code
      - name: Checkout Code
        uses: actions/checkout@v4

      # Step 2: Build your project / Generate artifacts (Example)
      # - name: Build Project
      #   run: npm run build # Replace with your build command
      # - name: Create Dummy Artifact
      #   run: echo "Release artifact content" > release_artifact.txt

      # Step 3: Use the Seal GitHub Action to upload
      - name: Upload Artifacts to Seal
        # Use the action directly from its repository
        uses: opvia/seal-github-actions/.github/actions/upload-artifacts@main # Use specific ref/tag
        with:
          # Seal API Configuration
          seal_api_token: ${{ secrets.SEAL_API_TOKEN }}
          seal_api_base_url: 'https://YOUR_SEAL_API_BASE_URL/'

          # Seal Template and Field Configuration
          seal_template_id: 'YOUR_SEAL_CHANGE_CONTROL_TEMPLATE_ID'
          seal_field_name: 'Release Artifact(s)' # Field created in Seal
          seal_file_type_title: 'GitHub-Artifacts' # Optional: Categorizes files

          # --- Specify Artifacts to Upload ---
          # Use glob patterns relative to the workspace root
          artifact_patterns: dist/**/*.js,docs/*.pdf,release_artifact.txt # Add more patterns as needed