GitHub Actions Docs Deployment Setup¶

This document explains how to set up AWS OIDC for GitHub Actions to auto-deploy documentation to S3.

Overview¶

The GitHub Actions workflow (.github/workflows/deploy-docs.yml) automatically:

Builds the MkDocs site
Deploys to S3 bucket vell-docs
Invalidates CloudFront cache

This runs on every push to main that modifies docs/** or mkdocs.yml.

AWS OIDC Setup¶

GitHub Actions uses OpenID Connect (OIDC) to authenticate with AWS without storing credentials.

Step 1: Create OIDC Identity Provider¶

Run this once in your AWS account:

aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com \
  --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1

Step 2: Create IAM Role¶

Create the IAM role that GitHub Actions will assume:

# Create trust policy
cat > github-actions-trust-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::253265132499:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:vell-io/vell-main:*"
        }
      }
    }
  ]
}
EOF

# Create the role
aws iam create-role \
  --role-name GitHubActionsDocsDeployment \
  --assume-role-policy-document file://github-actions-trust-policy.json

Step 3: Attach Permissions¶

Create and attach the permissions policy:

# Create permissions policy
cat > github-actions-permissions.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "S3Deployment",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl",
        "s3:GetObject",
        "s3:ListBucket",
        "s3:DeleteObject"
      ],
      "Resource": [
        "arn:aws:s3:::vell-docs",
        "arn:aws:s3:::vell-docs/*"
      ]
    },
    {
      "Sid": "CloudFrontInvalidation",
      "Effect": "Allow",
      "Action": [
        "cloudfront:CreateInvalidation",
        "cloudfront:GetInvalidation",
        "cloudfront:ListInvalidations"
      ],
      "Resource": "arn:aws:cloudfront::253265132499:distribution/E1XTO7UTGAUI9L"
    }
  ]
}
EOF

# Create the policy
aws iam create-policy \
  --policy-name GitHubActionsDocsDeploymentPolicy \
  --policy-document file://github-actions-permissions.json

# Attach policy to role
aws iam attach-role-policy \
  --role-name GitHubActionsDocsDeployment \
  --policy-arn arn:aws:iam::253265132499:policy/GitHubActionsDocsDeploymentPolicy

Step 4: Verify Setup¶

Test the role ARN matches the workflow:

aws iam get-role --role-name GitHubActionsDocsDeployment

Expected ARN: arn:aws:iam::253265132499:role/GitHubActionsDocsDeployment

This should match the role-to-assume value in .github/workflows/deploy-docs.yml.

Testing¶

Test Locally¶

Build and preview the docs locally:

# Activate venv
source ~/.venvs/vell-docs/bin/activate

# Build docs
mkdocs build

# Preview
mkdocs serve
# Visit http://localhost:8000

Test Deployment Manually¶

Deploy manually to test:

# Build
mkdocs build

# Deploy to S3
aws s3 sync site/ s3://vell-docs/ --delete

# Invalidate CloudFront
aws cloudfront create-invalidation \
  --distribution-id E1XTO7UTGAUI9L \
  --paths "/*"

Test GitHub Actions¶

Trigger the workflow:

Make a change to any file in docs/
Commit and push to main branch
Check GitHub Actions tab for workflow run
Visit https://docs.vell.ai to verify deployment

Or trigger manually:

Go to Actions tab in GitHub
Select "Deploy Documentation" workflow
Click "Run workflow"
Select branch and run

Monitoring¶

Workflow Status¶

Check workflow runs: - https://github.com/vell-io/vell-main/actions

S3 Bucket¶

View deployed files:

aws s3 ls s3://vell-docs/ --recursive

CloudFront¶

Check invalidation status:

aws cloudfront list-invalidations \
  --distribution-id E1XTO7UTGAUI9L

Troubleshooting¶

Permission Denied Errors¶

If the workflow fails with permission errors:

Verify OIDC provider exists
Check IAM role trust policy
Verify policy is attached to role
Check role ARN matches workflow

Build Failures¶

If MkDocs build fails:

Test locally: mkdocs build --strict
Check for broken links
Verify markdown syntax
Check image paths

CloudFront Not Updating¶

If changes don't appear:

Check invalidation status
Try hard refresh (Cmd+Shift+R or Ctrl+F5)
Wait 5-10 minutes for cache invalidation
Check CloudFront distribution status

Security Notes¶

✅ No AWS credentials stored in GitHub
✅ OIDC provides temporary credentials per workflow run
✅ Role limited to specific repository
✅ Least privilege permissions
✅ CloudFormation manages infrastructure

Updating¶

To update deployment settings:

Edit .github/workflows/deploy-docs.yml
Test locally first
Commit and push to main
Monitor workflow run

Rolling Back¶

If a deployment breaks the site:

Find last good commit: git log --oneline docs/
Revert changes: git revert <commit-hash>
Push to main
Workflow auto-deploys previous version

Or deploy manually from a previous commit:

git checkout <good-commit-hash>
mkdocs build
aws s3 sync site/ s3://vell-docs/ --delete
git checkout main