CI/CD Workflows

Automate your Hammer site builds and deployments with Git-based CI/CD workflows. Connect your repository to Forge and deploy on every push.

Introduction

Advanced CI/CD workflows allow you to automate your Hammer site builds and deployments using Git repositories. With Git integration, every push to your repository can trigger an automatic build and deployment to Forge.

Using Git-based CI/CD workflows provides:

  • Automated builds triggered by Git pushes
  • Version control for your entire Hammer project
  • Team collaboration with multiple contributors
  • Branch-based deployments for staging and production
  • Deployment history tied to your Git commits
Tip: CI/CD workflows are perfect for teams and production workflows where you want automated deployments without manual intervention.

Setting Up Your Hammer Project in Git

Before configuring CI/CD, you'll need to set up your Hammer project in a Git repository hosted on GitHub, Bitbucket, or another Git hosting service.

Initializing Git

If your Hammer project isn't already in a Git repository, initialize it:

cd /path/to/your/hammer-project
git init
git add .
git commit -m "Initial commit"

Creating a .gitignore File

It's important to exclude the Build directory from version control since it's generated automatically. Create or update your .gitignore file:

# Hammer build output
Build/

# OS files
.DS_Store
Thumbs.db

# Editor files
.vscode/
.idea/
*.swp
*.swo

The Build/ directory should never be committed to Git. Hammer Cloud will build your site fresh on each deployment, ensuring clean builds every time.

Note: Only commit your source files (HTML templates, CSS, JavaScript, assets, etc.) to Git. The Build directory is generated and should remain in .gitignore.

Pushing to Your Repository

Create a repository on your preferred Git hosting service (GitHub, Bitbucket, etc.) and push your project:

git remote add origin https://github.com/yourusername/your-repo.git
git branch -M main
git push -u origin main

Replace the repository URL with your actual repository URL from GitHub, Bitbucket, or your Git hosting service.

Connecting Git to Your Forge Site

Once your Hammer project is in a Git repository, you can connect it to your Forge site for automated builds and deployments.

Step 1: Connect Your Git Provider

In your Forge account, you'll need to connect your Git hosting service:

  1. Navigate to your Forge site settings
  2. Go to the Git Integration or Source section
  3. Click Connect GitHub or Connect Bitbucket
  4. Authorize Forge to access your Git repositories

You can connect multiple Git accounts and choose which account to use for each site. Forge supports:

  • GitHub - Public and private repositories
  • Bitbucket - Public and private repositories
  • Other Git providers that support OAuth authentication

Step 2: Select Your Repository

After connecting your Git provider, select the repository containing your Hammer project:

  1. Choose the repository from the list of available repositories
  2. Select the branch you want to deploy (typically main or master)
  3. Configure the repository connection settings
Tip: You can use different branches for different environments. For example, deploy the main branch to production and develop branch to staging.

Configuring Hammer Cloud Service

Forge uses Hammer Cloud as the build service for Hammer projects. This service automatically detects Hammer projects and builds them using the Hammer compiler.

Step 1: Enable Hammer Cloud

In your Forge site settings:

  1. Navigate to the Build Settings or Services section
  2. Select Hammer Cloud from the available build services
  3. Configure the build service (Hammer Cloud will auto-detect your Hammer project structure)

Hammer Cloud automatically:

  • Detects Hammer template syntax in your repository
  • Identifies the project structure and configuration
  • Builds your site using the Hammer compiler
  • Outputs the built site to the Build directory

Step 2: Configure Build Settings

Hammer Cloud uses sensible defaults, but you can customize build settings if needed:

  • Build command: Automatically set to use Hammer Cloud
  • Output directory: Typically Build/
  • Build environment: Configured for Hammer projects
Note: Hammer Cloud handles all the build complexity for you. You don't need to configure build commands or scripts. Hammer Cloud knows how to build Hammer projects.

Automatic vs Manual Deployment

Forge gives you control over when deployments happen. You can choose between automatic deployments on every push or manual deployments triggered from your Git provider.

Automatic Deployment

With automatic deployment enabled:

  • Every push to your connected branch triggers a build
  • Hammer Cloud builds your site automatically
  • The site deploys to Forge as soon as the build completes
  • You receive notifications about build and deployment status

To enable automatic deployment:

  1. Go to your Forge site settings
  2. Navigate to Deployment Settings
  3. Enable Auto-deploy or Automatic deployments
  4. Save your settings

Manual Deployment

With automatic deployment disabled:

  • Pushes to your repository trigger a build, but not a deployment
  • You can review the build status in Forge
  • Deploy manually when ready from Forge's dashboard or GitHub/Bitbucket integration
  • Useful for staging or when you want to control deployment timing

To deploy manually:

  1. View your site in Forge dashboard
  2. Review the latest build from your Git repository
  3. Click Deploy when ready
  4. Or use the "Deploy" button from your Git provider's interface
Best Practice: Enable auto-deploy for your production branch (main) and use manual deployment for feature branches or staging environments.

Complete CI/CD Workflow

Here's how the complete workflow functions when everything is configured:

The Deployment Flow

  1. Push to Git: You or your team members push changes to the connected branch
  2. Webhook Trigger: Your Git provider sends a webhook to Forge notifying of the push
  3. Build Starts: Hammer Cloud begins building your Hammer site
  4. Template Processing: Hammer Cloud processes all Hammer templates, includes, variables, and directives
  5. Asset Processing: All assets are optimized and prepared for deployment
  6. Build Complete: The built site is ready in the Build directory
  7. Deployment: If auto-deploy is enabled, the site deploys automatically
  8. CDN Propagation: Changes propagate across Forge's global CDN
  9. Site Live: Your site is live with the latest changes

Monitoring Builds

You can monitor the status of your builds and deployments:

  • Forge Dashboard: View build logs, deployment history, and status
  • Git Integration: See build status directly in GitHub/Bitbucket pull requests
  • Notifications: Receive email or in-app notifications about build and deployment status
  • Build Logs: Access detailed logs for debugging failed builds

Branch-Based Workflows

Forge supports connecting multiple branches to different sites or environments:

  • Production: Connect main branch to your production site
  • Staging: Connect staging or develop branch to a staging site
  • Preview Deployments: Create temporary preview sites for pull requests

Troubleshooting

If you encounter issues with your CI/CD workflow, here are common solutions:

Build Failures

  • Check build logs: Review the detailed build logs in Forge for error messages
  • Verify .gitignore: Ensure Build/ is in .gitignore and not committed
  • Template errors: Hammer Cloud will report template syntax errors in build logs
  • Missing files: Ensure all required source files are committed to Git

Deployment Issues

  • Git connection: Verify your Git provider is connected and authorized
  • Branch selection: Confirm the correct branch is selected in Forge settings
  • Service configuration: Ensure Hammer Cloud service is enabled for your site
  • Permissions: Check that Forge has access to your repository

Next Steps

Now that you're set up with CI/CD workflows, you might want to: