Skip to content

SharePoint Static Site Deployment Setup Guide

This guide explains how to set up and use the SharePoint deployment workflow for the ABS Platform documentation.

Overview

The teams-sharepoint-deploy.yml workflow automatically compiles the documentation in the docs/ directory into a static site using MkDocs and deploys it to Microsoft SharePoint, making it accessible in Microsoft Teams.

Workflow Features

✅ Automatic builds - Triggers on push to main when docs change
✅ Manual deployment - Can be triggered via workflow_dispatch
✅ Validation - Checks for required secrets and build success
✅ Version management - Creates timestamped deployment folders
✅ Teams integration - Sends notifications with deployment links
✅ Error handling - Graceful failure handling with detailed logs

Prerequisites

⚠️ Important: SharePoint requires certificate-based authentication for app-only access. Client ID and secret authentication is not supported. See the Certificate Setup Guide for detailed instructions.

1. SharePoint Site Setup

You need a SharePoint site with: - A document library for hosting the documentation - Appropriate permissions for the service principal

2. Azure AD App Registration (Service Principal)

Create an Azure AD app registration:

  1. Go to Azure Portal → Azure Active Directory → App registrations
  2. Click "New registration"
  3. Name: GitHub Actions - ABS Docs Deployment
  4. Supported account types: Single tenant
  5. Click "Register"

After registration: - Note the Application (client) ID → This is SHAREPOINT_APP_ID - Note the Directory (tenant) ID → This is SHAREPOINT_TENANT_ID

3. Generate and Upload Certificate

Important: SharePoint requires certificate-based authentication. Follow the detailed guide: SharePoint Certificate Setup Guide

Quick Summary:

  1. Generate a certificate (PowerShell or OpenSSL)
  2. Upload the .cer file to Azure AD app registration
  3. Convert the .pfx file to Base64 for GitHub secret

PowerShell Quick Command: 

# Generate certificate
$cert = New-SelfSignedCertificate -Subject "CN=GitHubActions-ABSDocs" `
    -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable `
    -NotAfter (Get-Date).AddYears(2)

# Export PFX and CER
$password = ConvertTo-SecureString -String "YourStrongPassword!" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath "cert.pfx" -Password $password
Export-Certificate -Cert $cert -FilePath "cert.cer"

# Convert to Base64
[Convert]::ToBase64String([IO.File]::ReadAllBytes("cert.pfx")) | Out-File "cert-base64.txt"

Upload to Azure AD: 1. Go to your app registration → "Certificates & secrets" 2. Under "Certificates" tab, click "Upload certificate" 3. Select the cert.cer file 4. Click "Add"

4. Grant SharePoint Permissions

Grant the app permissions to access SharePoint:

  1. In your app registration, go to "API permissions"
  2. Click "Add a permission"
  3. Choose "SharePoint"
  4. Choose "Application permissions"
  5. Add these permissions:
  6. Sites.ReadWrite.All (or Sites.Selected for more security)
  7. Click "Add permissions"
  8. Click "Grant admin consent" for your tenant

5. SharePoint Site Permissions

Grant the app access to your specific SharePoint site:

# Install PnP PowerShell if needed
Install-Module PnP.PowerShell -Scope CurrentUser

# Connect to your SharePoint site
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/yoursite" -Interactive

# Grant the app permissions
Grant-PnPAzureADAppSitePermission `
    -AppId "YOUR_APP_ID" `
    -DisplayName "GitHub Actions - ABS Docs" `
    -Permissions Write

GitHub Secrets Configuration

Configure the following secrets in your GitHub repository:

Go to: Repository Settings → Secrets and variables → Actions → New repository secret

Required Secrets (Certificate Authentication)

Secret Name Description Example
SHAREPOINT_SITE_URL Your SharePoint site URL https://yourtenant.sharepoint.com/sites/yoursite
SHAREPOINT_DOCUMENT_LIBRARY Document library folder name Documentation or Shared Documents/Documentation
SHAREPOINT_APP_ID Azure AD App (client) ID 12345678-1234-1234-1234-123456789abc
SHAREPOINT_CERTIFICATE_BASE64 Base64-encoded PFX certificate Contents of cert-base64.txt file
SHAREPOINT_CERTIFICATE_PASSWORD PFX certificate password The password you set when creating PFX
SHAREPOINT_TENANT_ID Azure AD Directory (tenant) ID 87654321-4321-4321-4321-cba987654321

Note: SHAREPOINT_CERTIFICATE_BASE64 should be the entire base64 string (no line breaks in the GitHub secret, though the file may have them)

⚠️ Only use if you cannot use certificate authentication

Secret Name Description
SHAREPOINT_USERNAME SharePoint admin username
SHAREPOINT_PASSWORD SharePoint admin password
SHAREPOINT_SITE_URL Your SharePoint site URL
SHAREPOINT_DOCUMENT_LIBRARY Document library folder name

Note: Still need SHAREPOINT_APP_ID and SHAREPOINT_TENANT_ID are NOT required for username/password auth.

Optional Secrets

Secret Name Description Required
TEAMS_WEBHOOK_URL Incoming webhook URL for Teams notifications Optional

Creating a Teams Webhook (Optional)

To receive deployment notifications in Teams:

  1. In Teams, go to the channel where you want notifications
  2. Click "..." → "Connectors" → "Incoming Webhook"
  3. Name: Documentation Deployment
  4. Upload an icon (optional)
  5. Click "Create"
  6. Copy the webhook URL
  7. Add it as TEAMS_WEBHOOK_URL secret in GitHub

Usage

Automatic Deployment

The workflow automatically triggers when: - Changes are pushed to the main branch - Changes are made to files in the docs/ directory - The workflow file itself is modified

Manual Deployment

To manually trigger a deployment:

  1. Go to your repository on GitHub
  2. Click "Actions" tab
  3. Select "Deploy Docs to SharePoint for Teams"
  4. Click "Run workflow"
  5. Select branch (usually main)
  6. Click "Run workflow"

Workflow Steps

The workflow performs these steps:

  1. Checkout - Clones the repository with full history
  2. Setup Python - Installs Python 3.x with dependency caching
  3. Install Dependencies - Installs MkDocs and plugins from docs/requirements.txt
  4. Build Documentation - Compiles docs using MkDocs (Teams-optimized config if available)
  5. Validate Secrets - Checks all required secrets are configured
  6. Setup Node.js - Installs Node.js for SharePoint CLI
  7. Install SharePoint CLI - Installs Microsoft 365 CLI tools
  8. Authenticate - Logs into SharePoint using service principal
  9. Prepare Deployment - Creates deployment folder and copies files
  10. Deploy to SharePoint - Uploads all files to SharePoint document library
  11. Send Notification - Sends Teams notification (if configured)

Deployment Structure

Files are deployed to SharePoint in this structure:

Shared Documents/
└── [SHAREPOINT_DOCUMENT_LIBRARY]/
    └── abs-platform-docs-[BUILD_NUMBER]/
        ├── index.html
        ├── deployment-info.json
        ├── teams-redirect.html
        ├── assets/
        ├── business/
        ├── architecture/
        └── ...

Each deployment creates a new timestamped folder, allowing you to: - Keep multiple versions - Roll back if needed - See deployment history

Accessing the Documentation

After deployment, access your documentation at:

https://yourtenant.sharepoint.com/sites/yoursite/Shared Documents/[LIBRARY]/abs-platform-docs-[BUILD]/index.html

Adding to Teams Tab

  1. In Teams, go to your channel
  2. Click "+" to add a tab
  3. Choose "Website"
  4. Name: ABS Platform Docs
  5. URL: Your SharePoint documentation URL
  6. Click "Save"

Troubleshooting

Build Fails: "Module not found"

Solution: Ensure all required packages are in docs/requirements.txt

pip install -r docs/requirements.txt
mkdocs build --config-file docs/mkdocs.yml --strict

Authentication Fails

Possible causes: - App secret expired → Generate new secret - Missing permissions → Check API permissions in Azure AD - Site permissions not granted → Run Grant-PnPAzureADAppSitePermission

Files Not Uploading

Check: - Document library name is correct - Service principal has Write permissions - SharePoint site URL is correct (no trailing slash)

Teams Notification Not Sent

This is non-critical. Check: - TEAMS_WEBHOOK_URL secret is set correctly - Webhook hasn't been deleted in Teams - Webhook URL is complete (should start with https://)

Monitoring

View Deployment Logs

  1. Go to "Actions" tab in GitHub
  2. Click on the workflow run
  3. Click on "build-and-deploy" job
  4. Expand each step to see detailed logs

Deployment Metadata

Each deployment includes a deployment-info.json file with: - Deployment timestamp - Git commit SHA - Branch name - Build number - Who triggered the deployment

Best Practices

  1. Test locally first - Run mkdocs build locally before pushing
  2. Use draft PRs - Test documentation changes in pull requests
  3. Monitor builds - Check GitHub Actions for any warnings
  4. Regular secret rotation - Rotate app secrets periodically
  5. Backup important versions - Keep important deployment folders

Advanced Configuration

Using Teams-Optimized Config

The workflow checks for docs/mkdocs-teams.yml and uses it if available. This allows you to: - Customize theme for Teams viewing - Enable Teams-specific features - Optimize for iframe display

Custom Deployment Folder

To change the document library location, update the SHAREPOINT_DOCUMENT_LIBRARY secret.

Multiple Environments

Create separate workflows for different environments: - teams-sharepoint-deploy-staging.yml → Staging site - teams-sharepoint-deploy-prod.yml → Production site

Each with different secrets for different SharePoint sites.

Security Considerations

  1. Service Principal - Use app permissions, not delegated user permissions
  2. Least Privilege - Grant minimum required SharePoint permissions
  3. Secret Rotation - Rotate client secrets regularly (every 6-12 months)
  4. Audit Logs - Monitor SharePoint audit logs for app activity
  5. Site Isolation - Use dedicated SharePoint site for documentation

Support

If you encounter issues:

  1. Check the GitHub Actions logs for detailed error messages
  2. Verify all secrets are configured correctly
  3. Test SharePoint CLI authentication locally: 
    npm install -g @pnp/cli-microsoft365
m365 login --authType servicePrincipal --appId YOUR_APP_ID --appSecret YOUR_SECRET --tenant YOUR_TENANT
  4. Review Azure AD app permissions and SharePoint site permissions

Last Updated: 2025-10-08
Workflow Version: 2.0 (Corrected and Enhanced)