Workflows

The Agility CLI allows you to pull, push, or clone an instance from your console. This guide gives you best practices on how to integrate the Agility CLI into your CI/CD pipelines to automate content synchronization between Agility CMS instances.

# CI/CD Integration Guide

This guide explains how to integrate the Agility CLI into your CI/CD pipelines to automate content synchronization between Agility CMS instances.

## Overview

The typical CI/CD workflow involves:

1. **Pull** the repository containing your Agility mappings
2. **Run** the CLI sync command to synchronize content between instances
3. **Push** the updated mappings back to the repository

Persisting mappings in a Git repository ensures that content relationships are maintained across sync operations and prevents duplicate content creation.

---

## Prerequisites

### 1. Personal Access Token (PAT)



In CI/CD environments, browser-based authentication is not available. You must use a **Personal Access Token (PAT)** for authentication.

**To obtain a PAT:** Personal Access Tokens are created and managed using the management API which are documented in the "Personal Access Tokens" section of our Management API Swagger documentation found here: https://mgmt.aglty.io/index.html


### 2. Required Permissions

The user associated with the PAT must have one of the following roles:

- Org Admin
- Instance Admin
- Manager role on both source and target instances

### 3. Instance GUIDs

You'll need the GUIDs for both your source and target instances:

- **Source GUID**: The instance you're pulling content from
- **Target GUID**: The instance you're pushing content to

Find these in **Settings** → **Instance Details** in your Agility CMS dashboard.

---

## Environment Variables

Configure these environment variables in your CI/CD platform:

| Variable | Required | Description |
|----------|----------|-------------|
| `AGILITY_TOKEN` | Yes | Personal Access Token for authentication |
| `AGILITY_GUID` | Yes | Source instance GUID |
| `AGILITY_TARGET_GUID` | Yes | Target instance GUID |
| `AGILITY_LOCALES` | No | Comma-separated locales (e.g., `en-us,fr-ca`) |
| `AGILITY_ELEMENTS` | No | Elements to sync (default: all) |
| `AGILITY_ROOT_PATH` | No | Local directory for files (default: `agility-files`) |

---

## Headless Mode

When running in CI/CD, use the `--headless` flag to:

- Disable interactive console output
- Log all output to files instead
- Prevent terminal UI elements that may cause issues in non-TTY environments

```bash
agility sync --headless --sourceGuid="$SOURCE_GUID" --targetGuid="$TARGET_GUID"
```

---

## Sample Pipeline Configurations

### GitHub Actions

```yaml
name: Agility CMS Sync

on:
  # Trigger manually or on schedule
  workflow_dispatch:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM UTC

env:
  AGILITY_TOKEN: ${{ secrets.AGILITY_TOKEN }}
  SOURCE_GUID: ${{ vars.AGILITY_SOURCE_GUID }}
  TARGET_GUID: ${{ vars.AGILITY_TARGET_GUID }}

jobs:
  sync:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Agility CLI
        run: npm install -g @agility/cli

      - name: Run Agility Sync
        run: |
          agility sync \
            --headless \
            --sourceGuid="$SOURCE_GUID" \
            --targetGuid="$TARGET_GUID"

      - name: Commit and push mappings
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          
          # Add only the mappings directory
          git add agility-files/mappings/
          
          # Check if there are changes to commit
          if git diff --staged --quiet; then
            echo "No mapping changes to commit"
          else
            git commit -m "chore: update Agility CMS mappings [skip ci]"
            git push
          fi
```

### GitHub Actions - Multi-Environment

```yaml
name: Agility CMS Multi-Environment Sync

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        type: choice
        options:
          - staging
          - production

jobs:
  sync:
    runs-on: ubuntu-latest
    environment: ${{ github.event.inputs.environment }}
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Agility CLI
        run: npm install -g @agility/cli

      - name: Run Agility Sync
        env:
          AGILITY_TOKEN: ${{ secrets.AGILITY_TOKEN }}
        run: |
          agility sync \
            --headless \
            --sourceGuid="${{ vars.AGILITY_SOURCE_GUID }}" \
            --targetGuid="${{ vars.AGILITY_TARGET_GUID }}" \
            --locales="${{ vars.AGILITY_LOCALES }}"

      - name: Commit and push mappings
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          
          git add agility-files/mappings/
          
          if git diff --staged --quiet; then
            echo "No mapping changes to commit"
          else
            git commit -m "chore: update Agility CMS mappings (${{ github.event.inputs.environment }}) [skip ci]"
            git push
          fi
```


---

## Advanced Configuration

### Selective Sync by Elements

Sync only specific content types:

```bash
agility sync \
  --headless \
  --sourceGuid="$SOURCE_GUID" \
  --targetGuid="$TARGET_GUID" \
  --elements="Models,Content,Assets"
```

Available elements: `Models`, `Galleries`, `Assets`, `Containers`, `Content`, `Templates`, `Pages`

### Model-Specific Sync

Sync specific models with their dependencies:

```bash
agility sync \
  --headless \
  --sourceGuid="$SOURCE_GUID" \
  --targetGuid="$TARGET_GUID" \
  --models-with-deps="BlogPost,BlogCategory"
```

### Locale-Specific Sync

Sync only specific locales:

```bash
agility sync \
  --headless \
  --sourceGuid="$SOURCE_GUID" \
  --targetGuid="$TARGET_GUID" \
  --locales="en-us,fr-ca"
```

---

## Workflow Operations

After syncing content, you can perform workflow operations (publish, approve, etc.) on the synced items:

```bash
# Publish all synced content and pages
agility workflows \
  --headless \
  --sourceGuid="$SOURCE_GUID" \
  --targetGuid="$TARGET_GUID" \
  --operationType="publish"
```

Available operations: `publish`, `unpublish`, `approve`, `decline`, `requestApproval`

### Full Sync + Publish Pipeline Example

```yaml
# GitHub Actions example with sync and publish
- name: Sync and Publish Content
  run: |
    # First, sync the content
    agility sync \
      --headless \
      --sourceGuid="$SOURCE_GUID" \
      --targetGuid="$TARGET_GUID"
    
    # Then, publish the synced content
    agility workflows \
      --headless \
      --sourceGuid="$SOURCE_GUID" \
      --targetGuid="$TARGET_GUID" \
      --operationType="publish"
```

---

## Best Practices

### 1. Store Mappings in Version Control

Always commit your `agility-files/mappings/` directory to your repository. This ensures:

- Consistency across pipeline runs
- Rollback capability
- Audit trail of sync operations
- Prevention of duplicate content creation

### 2. Use `[skip ci]` in Commit Messages

Include `[skip ci]` in mapping commit messages to prevent infinite pipeline loops:

```bash
git commit -m "chore: update Agility CMS mappings [skip ci]"
```

### 3. Separate Environments

Use different branches or repositories for different environment mappings:

```
main branch       → Production sync mappings
staging branch    → Staging sync mappings
develop branch    → Development sync mappings
```

### 4. Scheduled Runs

Set up scheduled pipeline runs for regular sync operations:

```yaml
# GitHub Actions cron syntax: minute hour day month weekday
schedule:
  - cron: '0 2 * * *'  # Daily at 2 AM UTC
```

### 5. Artifact Retention

Keep sync logs as artifacts for debugging:

```yaml
artifacts:
  paths:
    - agility-files/logs/
  expire_in: 7 days
```

### 6. Handle Failures Gracefully

Use the exit code to handle sync failures:

```bash
agility sync --headless --sourceGuid="..." --targetGuid="..." || {
  echo "Sync failed, check logs for details"
  exit 1
}
```

---

## Troubleshooting

### Authentication Errors

- Verify the PAT is valid and not expired
- Ensure the token has sufficient permissions
- Check that the `AGILITY_TOKEN` secret is properly configured

### SSL Certificate Errors

In corporate environments with proxy servers, use the `--insecure` flag:

```bash
agility sync --headless --insecure --sourceGuid="..." --targetGuid="..."
```

### Missing Mappings

If mappings are missing, the CLI will create new content instead of updating existing content. Always ensure:

- The `agility-files/mappings/` directory is committed to your repository
- The pipeline checks out the full repository (not a shallow clone)

### Duplicate Content

If duplicates are being created:

1. Stop all concurrent sync operations
2. Restore mappings from a known good state
3. Run a fresh sync with `--update=true` to rebuild mappings

---

## Support

- **Documentation**: [Agility CMS Doc Site](https://agilitycms.com/docs)
- **Community**: [Agility Slack](https://join.slack.com/t/agilitycommunity/shared_invite/enQtNzI2NDc3MzU4Njc2LWI2OTNjZTI3ZGY1NWRiNTYzNmEyNmI0MGZlZTRkYzI3NmRjNzkxYmI5YTZjNTg2ZTk4NGUzNjg5NzY3OWViZGI)
- **Issues**: [GitHub Issues](https://github.com/agility/agility-cms-management-cli/issues)

APIs

CLI - CI/CD Integration Guide

System Status

Privacy Policy

GDPR

Security

Glossary

Headless CMS

Composable DXP

Enterprise

Marketers

Developers

Features

Roadmap

Pricing

Platform

App Marketplace

Ecosystem Partners

MACH Alliance Member

Case Studies

Solutions on Agility

Customers & Partners 

ROI Calculator

Resource Center

Documentation

Blog

Starters

Headless CMS Comparison

Resources

100% Canadian

Leadership

Core Values

Events

Careers

Contact Us

About Us

G2 Reviews

YouTube

Instagram

Slack Community

Subscribe to our Newsletter

Overview

Editors

Owners & Admins

Training Guide

Apps

<p>What is your developer-dependent CMS actually costing you? <a class="link-line line-purple" href="/Developer-Dependent-CMS-Calculator" rel="noopener">Calculate your costs and get a full report</a></p>

##Title##

developers-articles-dynamic

cli-ci-cd-integration-guide