Documentation

Overview

ATGitOps Helper is a workspace for Adobe Target GitOps. Each project ties a GitHub repository to Adobe Target MCP. You author offers in the visual composer, open a pull request, and when that PR merges to main, GitHub Actions creates or updates the activity in Adobe Target.

Getting started

1. Run the helper
   From at-git-helper, run npm run dev and open http://localhost:3847.
2. MongoDB
   Default URI is mongodb://127.0.0.1:27017/atgitops. Override with MONGODB_URI in .env.local.
3. Sign in
   Register an account or sign in. Projects and credentials are stored per user.
4. Create a project
   Use Create project or Add new project on the home dashboard.

cd at-git-helper
npm install
npm run dev
# Open http://localhost:3847

Project setup

A project is a named workspace with its own GitHub repo and Target MCP credentials. Switch projects anytime from the header switcher.

Add project wizard (4 steps)

1. Project
   Name, project ID, client, and optional description.
2. GitHub
   Sign in with GitHub, pick or paste the repo URL/branch, add SSH key for private repos if needed.
3. MCP
   Connect Adobe Target MCP (Sign in with Adobe recommended). Optionally push credentials to GitHub Actions.
4. Deploy / bootstrap
   Optionally push GitOps boilerplate, a sample XT activity, and sync Actions secrets/variables.

GitHub setup

GitHub is where activity folders live and where deploy runs. Prefer OAuth over pasting a PAT.

Recommended path

1. Sign in with GitHub
   Requires GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET in .env.local.
2. Choose the repository
   Use the account/organization switcher and repo picker, or paste HTTPS/SSH URLs. Set the working branch (usually main). If an org is missing, reconnect GitHub (read:org) and grant the OAuth app under the org’s Third-party access settings.
3. Private repos
   Add the helper SSH key once (Project settings → GitHub) so git push/bootstrap can reach the repo.
4. Bootstrap
   On the Deploy step, push boilerplate including .github/workflows/deploy.yml, scripts, and templates. Empty repos bootstrap onto main.

Actions secrets & variables

Deploy needs these on the repo (synced from the MCP step when enabled, or managed under workspace → Actions / Project settings):

• Secrets: ADOBE_ACCESS_TOKEN, ADOBE_CLIENT_ID, ADOBE_CLIENT_SECRET
• Variables: DEPLOY_USERNAME, MCP_SERVER_URL

Adobe Target MCP setup

MCP is how the helper and GitHub Actions talk to Adobe Target — list audiences, create activities after merge, and update offers.

Recommended: Sign in with Adobe

1. MCP server URL
   Default is https://targetmcp.adobe.io/mcp.
2. Browser OAuth
   Click Sign in with Adobe. Complete Adobe login; the helper stores the MCP session for the project.
3. Deploy username
   Set the Adobe / Target deploy username used by Actions.
4. Push to Actions
   Enable “Push MCP credentials to GitHub Actions” so deploy.yml can authenticate after merge.

Advanced credentials

Under Advanced you can paste an access token and/or client ID/secret instead of browser OAuth. Use this for service accounts or when OAuth is unavailable.

Create a Target activity

From a project workspace → Activities → New activity. Flow: Setup → Composer → Publish (GitHub PR).

1. Setup

• Activity name — human label (also drives the GitHub folder name).
• Type
  • XT — Experience Targeting (personalization; no traffic split)
  • AB — A/B test with traffic split
  • ABT — Auto-Allocate toward a winner
• Page URL — used for page preview and page-delivery context.
• Experiences — add up to 8; each has an experience name and offer name.
• Targeting — optional audiences, mbox (default target-global-mbox), and schedule. Empty audiences = all visitors.

Click Continue to composer. This only builds a local draft — Target create is deferred until merge to main.

2. Composer

Edit Offer Styles (CSS) and JS against a live page preview. Switch experiences with the A / B / … tabs; the active offer is what injects into preview. Use Build with AI when the preview can read the page.

3. Publish

Click Open PR to GitHub. The helper creates a branch, commits the activity folder, and opens a pull request against main.

przepisy_homepage_personalization_xt_test/
├── activity-info.json
└── przepisy_homepage_personalization_xt_test_exp_a.html

Composer & page preview

Preview modes control how the Page URL loads in the iframe:

Build with AI

Generate offer CSS and JS from a natural-language prompt while the page preview is loaded. The helper samples palette and fonts from the live page so popups, banners, and copy changes match site branding.

1. Add an AI agent
   Account settings → AI agents → paste a Cursor API key.
2. Load preview
   Use Proxy or Extension until the Page URL renders. AI needs a readable preview for theme/fonts.
3. Optional: Pick element
   Target one node in preview, then describe the change (e.g. change headline, restyle CTA).
4. Choose Cursor mode
   Cloud API uses your key against Cursor cloud. Live workspace runs against a local workspace when available.
5. Generate
   Watch the planning log for captured theme/fonts, then confirm the offer injects into Page Preview. Adjust Styles/JS manually if needed before Open PR.

Walkthrough: Przepisy.pl Experience Targeting

End-to-end example using an existing project and https://www.przepisy.pl/ as the page under test.

1. Open the project workspace
   Home → select project → Open workspace → Activities → New activity.
2. Fill setup for XT personalization
   • Name: Przepisy homepage personalization
   • Type: Experience Targeting (XT)
   • Page URL: https://www.przepisy.pl/
   • Folder (auto): przepisy_homepage_personalization_xt_test
   • Description: personalize homepage hero / featured recipes for a target audience
   • Leave audiences empty for all visitors, or search and attach a reusable Target audience
3. Continue to composer
   Confirm the step indicator shows Composer. Page URL should already be https://www.przepisy.pl/.
4. Load preview (WAF sites)
   Przepisy.pl often blocks Proxy preview (Akamai / WAF). Switch to Extension, install/reload the browser extension, then Enable with extension. Edit Styles/JS and verify the offer injects on the live homepage.
5. Shape the offer
   Use Styles + JS (or Build with AI after preview loads) to personalize headlines, CTAs, or banners. For XT you typically keep one experience; add more if you need alternate targeted offers.
6. Open PR to GitHub
   Publish creates a branch like activity/przepisy_homepage_personalization_xt_test and a PR against main. Example: PR #15 — “Add Target activity: Przepisy homepage personalization”.
7. Merge to deploy
   Review CI on the PR, merge to main, then watch Deploy Adobe Target in workspace → Actions. Target creates the XT activity after a successful deploy on main.

Deploy to Adobe Target

Deployment is Git-driven. Publishing from the helper only opens a PR; Target changes apply after merge.

1. Review the PR
   Check activity-info.json, offer HTML, and green CI validation on the pull request.
2. Merge to main
   Merge via GitHub UI or gh pr merge.
3. GitHub Actions deploy
   deploy.yml validates the activity folder and calls Target MCP to create (if missing) or update the activity and offers.
4. Watch from the helper
   Project workspace → Actions, or the Actions tab on GitHub. Confirm the run succeeds.
5. Activate in Target UI
   Deploy does not auto-activate. Open Adobe Target, QA the activity, then activate when ready.

Optional: create the PR from a local clone

If you edit files outside the helper, commit from your Target GitOps repo clone (not the at-git-helper app folder):

cd /path/to/your-target-gitops-repo
git checkout main && git pull origin main
git checkout -b activity/przepisy_homepage_personalization_xt_test
git add przepisy_homepage_personalization_xt_test/
git commit -m "$(cat <<'EOF'
Add Przepisy homepage XT personalization.

EOF
)"
git push -u origin HEAD
gh pr create --title "Add Przepisy homepage personalization" --body "$(cat <<'EOF'
## Summary
- XT activity for https://www.przepisy.pl/
- Offer CSS/JS for homepage personalization

## Test plan
- [ ] PR validation passes
- [ ] After merge, Actions deploy succeeds
- [ ] Activity appears in Adobe Target

EOF
)"

Save deploy IDs

After the first successful create on main, Actions logs return activity_id and offer_id values. Save them into activity-info.json (helper Save IDs / Fetch IDs flows when available) so later PRs update the same Target activity instead of creating duplicates.

• activity_id — Adobe Target activity ID
• offer_id — HTML offer ID per experience

Troubleshooting