1  # Deployment
 2  
 3  This section details the deployment process for the AI-enhanced CV system, primarily focusing on GitHub Pages, and provides guidance on custom domains and troubleshooting.
 4  
 5  ## GitHub Pages Setup
 6  
 7  The AI-enhanced CV is designed to be automatically deployed to [GitHub Pages](https://pages.github.com/) with each successful run of the `🚀 CV Auto-Enhancement Pipeline` (`cv-enhancement.yml`) workflow.
 8  
 9  ### How it Works
10  
11  1.  **Build Output**: The `cv-generator.js` script generates all static website assets (HTML, CSS, JavaScript, data files, PDF) into the `dist/` directory.
12  2.  **Deployment Action**: The `peaceiris/actions-gh-pages@v3` GitHub Action is used to deploy the contents of the `dist/` directory to the `gh-pages` branch of the repository.
13  3.  **GitHub Pages Hosting**: GitHub Pages then serves the content from the `gh-pages` branch, making the CV accessible at a URL like `https://<username>.github.io/<repository-name>` (e.g., `https://adrianwedd.github.io/cv`).
14  
15  ### Configuration in `cv-enhancement.yml`
16  
17  The deployment step in the workflow is configured as follows:
18  
19  ```yaml
20        - name: 🚀 Deploy to GitHub Pages
21          uses: peaceiris/actions-gh-pages@v3
22          with:
23            github_token: ${{ secrets.GITHUB_TOKEN }}
24            publish_dir: ./dist
25            cname: ${{ secrets.CUSTOM_DOMAIN }}
26  ```
27  
28  *   **`github_token`**: Uses the default `GITHUB_TOKEN` provided by GitHub Actions, which has sufficient permissions to push to the `gh-pages` branch.
29  *   **`publish_dir`**: Specifies that the `dist/` directory should be deployed.
30  *   **`cname`**: (Optional) Allows specifying a custom domain for the GitHub Pages site. This value is pulled from a GitHub Secret named `CUSTOM_DOMAIN`.
31  
32  ## Custom Domains
33  
34  To use a custom domain (e.g., `cv.yourdomain.com`) for your GitHub Pages CV, follow these steps:
35  
36  1.  **Configure DNS**: In your domain registrar's settings, create a `CNAME` record that points your desired subdomain (e.g., `cv`) to `<username>.github.io/<repository-name>` (e.g., `adrianwedd.github.io/cv`).
37  2.  **GitHub Secret**: Add your custom domain as a repository secret named `CUSTOM_DOMAIN` in your GitHub repository settings (`Settings > Secrets and variables > Actions > New repository secret`).
38  3.  **Workflow Execution**: The `cv-generator.js` script will automatically create a `CNAME` file in the `dist/` directory with your custom domain, which the `peaceiris/actions-gh-pages` action will then deploy.
39  
40  ## Troubleshooting Deployment Issues
41  
42  If your CV is not deploying correctly to GitHub Pages, consider the following:
43  
44  *   **Workflow Status**: Check the `Actions` tab in your GitHub repository. Ensure the `🚀 CV Auto-Enhancement Pipeline` workflow is completing successfully. Look for any failed steps.
45  *   **Permissions**: Verify that the `GITHUB_TOKEN` has `contents: write` and `pages: write` permissions in your workflow file.
46  *   **`publish_dir`**: Ensure the `publish_dir` in the deployment step (`./dist`) correctly points to the directory where your `cv-generator.js` script outputs the website files.
47  *   **`CNAME` File**: If using a custom domain, check the `gh-pages` branch of your repository to ensure the `CNAME` file exists and contains the correct domain name.
48  *   **Browser Cache**: Sometimes, browser cache can cause issues. Try clearing your browser's cache or opening the GitHub Pages URL in an incognito/private window.
49  *   **GitHub Pages Settings**: Verify your repository's GitHub Pages settings (`Settings > Pages`) to ensure it's configured to deploy from the `gh-pages` branch.
50  *   **Build Errors**: Check the logs of the `🎨 Dynamic CV Website Generation` step. Errors here will prevent the website files from being correctly generated.