Deploy with GitHub Pages

Choose a Workflow

GitHub Pages hosts static files from a GitHub repository. Functional Websites gives you two reasonable ways to get your site there:

Before You Start

• A GitHub account.
• A Functional Websites project ready to publish.
• For manual export: a repository and either Git installed locally or comfort using GitHub's browser upload flow.
• For direct deploy: Pro unlocked in the builder and a GitHub personal access token.

Option 1: Export and Publish Yourself

This path keeps GitHub credentials out of the builder. It is the simplest security model and ZIP export stays free.

Step 1: Export the Site

1. Open your project in the Site Builder.
2. Click Download ZIP.
3. Extract the ZIP on your computer.
4. Confirm the extracted folder contains index.html at the root.

Step 2: Create a Repository

1. Go to github.com/new.
2. Name the repository, for example my-website.
3. Choose Public unless you have a GitHub plan that supports Pages for private repositories.
4. Create the repository.

Step 3A: Upload in the Browser

1. Open your new repository on GitHub.
2. Choose uploading an existing file or Add file > Upload files.
3. Drag in the exported files and folders, including index.html.
4. Commit the upload to the main branch.

Step 3B: Or Push with Git

Open Terminal, navigate to your site folder, and run:

Replace: YOUR-USERNAME with your GitHub username and YOUR-REPO-NAME with your repository name.

Step 4: Enable GitHub Pages

1. Go to the repository on GitHub.
2. Open Settings.
3. Open Pages in the sidebar.
4. Set the source to Deploy from a branch.
5. Select main and the folder where your site files live, usually /root.
6. Save. Your site will publish at https://YOUR-USERNAME.github.io/YOUR-REPO-NAME.

Option 2: Deploy Directly from the Builder (Pro)

Direct GitHub deployment lets the builder create or update repository files for you. This is faster for repeated updates, but it requires a GitHub personal access token.

Step 1: Create a GitHub Token

1. Sign in to GitHub.
2. Open Settings from your GitHub profile menu.
3. Open Developer settings.
4. Open Personal access tokens.
5. Prefer a fine-grained token when possible. Limit it to the repository or organization you plan to deploy to.
6. Grant only the permissions needed to create/update repository contents. If you use classic tokens, avoid broad scopes unless you understand the risk.
7. Set an expiration date. Shorter is safer.
8. Generate the token and copy it once. GitHub will not show it again.

Step 2: Store the Token in the Builder

1. Open the Site Builder.
2. Unlock Pro if you have not already.
3. Open Settings.
4. Find GitHub Integration.
5. Paste your token into Personal Access Token.
6. Enter your default GitHub username or organization.
7. Click Save & Verify.

Step 3: Deploy

1. Open the project you want to publish.
2. Click Deploy.
3. Choose GitHub as the target.
4. Enter the repository name, branch, and optional folder.
5. Start the deploy. The builder will prepare the HTML files and upload them to GitHub.
6. After the files are in GitHub, enable GitHub Pages for that branch/folder if you have not already.

Protect Your GitHub Token

A GitHub token can allow code or tools to modify repositories under your account. Treat it like a password.

• Do not paste your token into chats, emails, public issues, screenshots, or repository files.
• Use the least access that works. Repository-specific fine-grained tokens are safer than broad account-wide tokens.
• Set an expiration date and rotate tokens periodically.
• Remove tokens you no longer use from GitHub's token settings.
• If a token is exposed, revoke it immediately and create a new one.
• Do not use a token from a shared or public computer.
• Remember that browser storage is not a vault. Direct deploy is convenient, but manual export is safer if you do not want credentials stored in the browser.

Custom Domains

1. Buy or use a domain from your registrar.
2. Open your domain's DNS settings.
3. For a subdomain such as www.example.com, create a CNAME record pointing to YOUR-USERNAME.github.io.
4. In GitHub, open repository Settings > Pages and enter your custom domain.
5. Wait for DNS and HTTPS certificate provisioning. This can take minutes or, in some cases, several hours.

Updating Your Site Later

• Manual export: download a fresh ZIP, replace the old files in your repository, and commit/push again.
• Direct deploy: open the project in the builder, click Deploy, and publish to the same repository/branch.
• For important launches, preview the site before deploy and keep a known-good ZIP backup.

Troubleshooting

Site Not Showing?

• Verify index.html is in the folder GitHub Pages is publishing.
• Check that Pages is enabled in repository settings.
• Wait a minute or two, then refresh.
• Check the repository's Actions or Pages status if GitHub reports a build or publish error.

Broken Links or Images?

• Make sure all exported HTML, CSS, JavaScript, and image files were uploaded.
• Keep folder names intact, especially the exported images folder.
• Check for uppercase/lowercase filename mismatches. GitHub hosting is case-sensitive.

Token or Deploy Errors?

• Confirm the token has access to the target repository or organization.
• Confirm the repository name and owner are spelled correctly.
• If GitHub returns Not Found, the token may not have permission even if the repository exists.
• If you suspect token exposure, revoke it in GitHub immediately.

Best Practices

• Use clear repository names: A readable repo name makes the GitHub Pages URL easier to share.
• Keep exports small: Compress large images before publishing.
• Test before publishing: Use Preview in the builder and check mobile layout.
• Protect credentials: Prefer manual export if you do not want to store a token in your browser.