Your First Deployment¶

This guide walks you through deploying your first application to the SubDepthTech Test Deployment Portal.

Prerequisites¶

Before you begin, ensure you have:

GitHub account with repository access
Cloudflare account (free tier works)
Git installed locally
Basic familiarity with GitHub Actions

Step 1: Configure Secrets¶

Set up required secrets in your GitHub repository:

1.1 Cloudflare API Token¶

Log in to Cloudflare Dashboard
Navigate to My Profile > API Tokens
Click Create Token > Use template (Edit Cloudflare Pages)
Copy the token

1.2 Add to GitHub Secrets¶

Go to your repository on GitHub
Navigate to Settings > Secrets and variables > Actions
Click New repository secret
Add the following secrets:

Secret Name	Value	Description
`CLOUDFLARE_API_TOKEN`	Your CF token	API access
`CLOUDFLARE_ACCOUNT_ID`	Your CF account ID	Account identifier

Step 2: Set Up Project Structure¶

2.1 Create Documentation Directory¶

mkdir -p showcase-site/docs
cd showcase-site

2.2 Create Configuration¶

Create mkdocs.yml:

site_name: My Test Deployment
site_description: Test deployment using Cloudflare Pages

theme:
  name: material
  palette:
    primary: indigo
    accent: deep purple

nav:
  - Home: index.md
  - Getting Started: getting-started.md

2.3 Add Content¶

Create docs/index.md:

# Welcome

This is my first test deployment!

2.4 Create Requirements¶

Create requirements.txt:

mkdocs-material>=9.5.0
mkdocs-minify-plugin>=0.8.0
pymdown-extensions>=10.7

Step 3: Add Workflows¶

3.1 Create Workflow Directory¶

mkdir -p .github/workflows

3.2 Add Deploy Workflow¶

Create .github/workflows/deploy-docs.yml:

name: Deploy to Cloudflare Pages

on:
  push:
    branches: [ deploy-pages ]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Build site
        run: |
          cd showcase-site
          pip install -r requirements.txt
          mkdocs build --strict

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: my-test-project
          directory: showcase-site/site
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}

  rollback:
    needs: deploy
    if: ${{ failure() }}
    runs-on: ubuntu-latest
    steps:
      - name: Rollback on failure
        run: |
          npx wrangler pages rollback --project-name my-test-project

Step 4: Deploy¶

4.1 Commit and Push¶

git add .
git commit -m "feat(docs): initial test deployment"
git push origin deploy-pages

4.2 Monitor Deployment¶

Go to Actions tab in GitHub
Click on the running workflow
Watch the deployment progress

4.3 Access Your Site¶

Once deployed, your site will be available at:

https://<deployment-id>--my-test-project.pages.dev

Step 5: Verify Rollback¶

5.1 Create a Failing Build¶

Intentionally break your build to test rollback:

Edit mkdocs.yml with invalid YAML
Commit and push
Watch the workflow fail
Verify rollback job executes

5.2 Check Rollback Status¶

The rollback job should:

Detect deployment failure
Execute wrangler rollback command
Restore previous successful deployment

Troubleshooting¶

Build Failures¶

Issue: MkDocs build fails

Solution:

# Test locally
cd showcase-site
pip install -r requirements.txt
mkdocs build --strict

Authentication Errors¶

Issue: Cloudflare API authentication fails

Solution: - Verify CLOUDFLARE_API_TOKEN is correct - Check token permissions (must include Cloudflare Pages Edit) - Ensure token hasn't expired

Rollback Not Triggering¶

Issue: Rollback doesn't execute on failure

Solution: - Verify needs: deploy dependency in rollback job - Check if: ${{ failure() }} condition is present - Review GitHub Actions permissions

Next Steps¶

Now that you've completed your first deployment:

Explore advanced features
Explore the rollback system
Review the webhook API for integrations