> ## Documentation Index
> Fetch the complete documentation index at: https://www.pagent.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Push a winning test to Contentful
> Connect a space, write a winning test into a preview environment, and hand it off to master.
Use this guide to connect a space, review a winning test in a preview environment, and hand the approved values to your team in `master`.
You need a pagent workspace admin for connection changes, writes, handoffs, and cleanup. Other members can prepare and save a mapping for an admin to write.
## Connect a space
1. Open the website in pagent.
2. Go to **Integrations**, find **Contentful**, and select **Connect**.
3. Sign in to Contentful and approve access.
4. Choose the space that holds the website's content. Check the space ID if names are duplicated.
5. Choose the source environment. Choose `master` if that is the environment your production site reads.
6. Enter an ID for pagent's preview environment. The default is `pagent-preview`.
7. Review the source and preview environment IDs, type the preview environment ID to confirm, then create it.
pagent uses Contentful OAuth. Contentful gives pagent an access token with the `content_management_manage` scope, which pagent stores encrypted. You do not paste a personal access token in the normal connection flow.
The Contentful account must be able to:
* read the selected space, environments, locales, content types, entries, and assets
* create and manage an environment in the space
* create, update, and publish entries and assets in the preview environment when you choose those actions
* update existing entries and create assets in the source environment during a handoff
* unpublish and delete entries that pagent creates when you use cleanup
Contentful can still limit these actions through the account's space role. Setup also needs a free environment slot.
During setup and preview runs, pagent treats the source environment as read-only.
The later handoff is a separate, explicit action that saves unpublished changes
on existing entries in the source environment.
### Source and preview environments
pagent copies the source environment into a preview environment in the same space. Push runs write into the preview environment. They do not write into `master`.
If the preview environment ID already exists, pagent asks you to confirm that you want to reuse it. Reusing does not replace its contents. pagent indexes the environment as it stands, does not own it, and will not recreate it later.
Creating a new environment normally takes a few minutes. The index starts after Contentful reports that the environment is ready.
## Index the preview environment
The index is pagent's local snapshot of the preview environment. pagent reads its locales, content types, entries, field values, entry links, and asset links. It uses that snapshot to:
* suggest the field behind each winning change
* search and browse entries while you map a change
* restrict matching to an entry and its linked subtree
* warn when an entry is shared or already has unpublished changes
The first index starts automatically. A typical refresh takes about a minute. A large space can take several minutes. The connection page shows entries processed and the last update, and indexing continues if you leave the page.
pagent also refreshes connected indexes nightly. Run a manual **Refresh index** when:
* an entry, field, content type, locale, or asset changed since the last successful index
* a new or renamed entry does not appear in search or mapping suggestions
* the connection reports that the index is more than 24 hours old
* you want a current snapshot before an important push
Only one full index can run at a time. pagent rejects another refresh while one is active. A refresh starts from the beginning, but keeps the existing cached entries available until the fresh snapshot is complete.
## Push a winning test
Open **Integrations > Contentful > Tests to push**, then open the test. The flow asks for one decision on each screen.
### 1. Choose locales
Select every exact locale that should receive the winning value. pagent starts with the locales from your last push on this Contentful connection. Locales from an existing field mapping take precedence. If no choice or mapping is saved, pagent selects none for you.
Review the selection on every run. If you choose several locales, pagent writes the same winning value into each one, so check the wording for every locale before publishing.
The list comes from the indexed preview environment. pagent never adds a related regional locale automatically.
### 2. Set the mapping scope
Choose where pagent should look for fields. pagent starts with the scope from your last push on this Contentful connection:
* **The whole space** searches every indexed entry. This is the default when no scope has been saved.
* **One entry and what it links to** searches only that entry's subtree. Use this when you know the root entry for the page. It is faster and avoids near-duplicate content from other markets or pages.
Scope changes field matching only. It does not change the entries in Contentful.
### 3. Choose how to write
Choose a write mode based on what you need to review and promote.
| Mode | What pagent does | Main consequence |
| --------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **Change the existing entries** | Updates the entries already used by the page in the preview environment. | This cannot be reversed by pagent. Shared entries can affect other preview pages. |
| **Copy the page, then change the copy** | Deep clones the root and its linked entry tree, then writes into the copies. | This is reversible and is the mode required for a handoff to `master`. |
| **Make one shallow draft copy** | Copies only entries that change and keeps links to original child entries. | Useful for a quick review, but not a standalone page to publish. |
For a handoff to `master`, choose **Copy the page, then change the copy**. pagent uses the copied preview tree to prove which existing entries in `master` should receive the values. It does not copy that tree into `master`.
A deep clone copies the root and every entry in its linked subtree. It rewrites Entry links inside the copy to point to the copied entries. Assets stay shared. Other pages keep their links to the original entries.
The later handoff writes into those original entries in `master`. If another page uses one of them, publishing the handoff can change that page too. Check each entry's links in Contentful before publishing.
### 4. Name the copied page
This step appears only for a deep clone. Choose the root entry, then review the prefilled name and slug for each selected locale. Slugs must be unique. pagent checks every slug before creating anything.
### 5. Choose drafts or published entries
**Save as drafts** is the default and safest review path. Your team publishes in Contentful after checking the result.
**Publish immediately** publishes entries in the preview environment as pagent writes them. It still does not publish anything in `master` when the connection uses a managed preview environment.
### 6. Map each change
For every winning change:
1. Compare the current website value with the winning value.
2. Review the proposed entry, field, content type, and locales.
3. If several ranked text matches appear, choose the correct one.
4. Add or remove targets if the value belongs in more than one field.
5. Confirm the mapping, or skip the change.
For an image change, pagent first looks for fields that link to the exact source Contentful asset. If it cannot identify that asset, it uses contextual matching.
Use **Wrong target?** to search entries by name, browse by content type, or choose a ranked alternative. Use **Write a different value** only when you deliberately want to override the winning value. pagent records that override in the run. Confirmed mappings are saved for later runs.
Confirming a mapping does not write to Contentful. Skipping a change overrides any saved mapping for this run. The change remains active through pagent's SDK and is recorded as skipped in this run.
### 7. Check the write
The check screen lists the target environment, entries, fields, locales, and draft or publish choice. Open **Every field pagent will write** to inspect the before and after values grouped by entry.
For in-place writes, review warnings about shared entries and unpublished edits. An in-place write can replace the current draft value. pagent cannot restore the previous value.
### 8. Write and review the result
Select the write button. pagent writes entry by entry in the background, so you can leave the page.
The result shows every written, skipped, and failed field. A partial failure does not roll back fields that already landed. Fix the reported cause before writing the run again. Writing again sends every confirmed field, not only the failures.
## Hand the result off to master
The handoff is available only after a completed deep-clone run. If `master` was your source environment, follow these steps:
1. Review the copied page in the preview environment.
2. Open **Integrations > Contentful > Draft handoff**.
3. Open the completed run. pagent reads the current entries in `master` and prepares a final review. This step does not write anything.
4. Check the entries, fields, locales, and result shown at the top of the review. Expand the field list and check every entry, field, locale, and before and after value.
5. Review warnings for existing unpublished changes, entries that have never been published, unchanged values, and assets that pagent needs to upload. pagent adds its values to the same draft when an entry already has unpublished changes.
6. Select the button to write the listed fields into `master`, then confirm the write. pagent checks the review again before it starts.
7. Wait for the handoff to become **Ready for your team**. You can leave the page while pagent writes.
8. Open every affected entry in Contentful. Check its field values, links, selected locales, and any unpublished work that was already present.
9. Publish the entries and any new assets through your normal Contentful process. pagent checks the entries before it marks the run merged, but it does not check asset publication.
10. Return to **Draft handoff** and select **Your team published these**. pagent checks that every entry it wrote is published at or past the version it wrote before marking the run as merged.
pagent writes into the entries that already exist in `master`. Contentful saves the new field values as unpublished changes on those entries. No second entry tree is created in `master`, and the published version stays live until your team publishes the changes.
pagent publishes nothing during the handoff. This includes assets uploaded for image changes. Your team must review and publish those assets in Contentful.
Before the write, pagent checks that `master` is ready, every selected locale still exists, the root tree still contains every mapped entry, and each mapped field still has the same type and locale behavior. It also checks that the values and unpublished-change state still match the final review. If something changes after the review opens, pagent writes nothing. Reopen the review to see the current values.
All field values for one entry succeed or fail together. A failure on another entry can still leave a partial handoff. pagent does not roll back values that landed. **Run it again** writes the same reviewed values into every field, not only the failed fields.
An in-place handoff cannot be undone by pagent. Contentful keeps each entry's
history. Restore or discard the unpublished changes in Contentful if you do
not want to publish them.
## What happens to the preview environment
The preview environment is not deleted automatically after a merge. It stays connected for later pushes.
The entries created by an individual deep-clone preview run also stay until you remove them. After you mark the handoff merged or discarded, open **Cleanup** to delete that run's preview entries. pagent checks Contentful for outside references immediately before deletion and only deletes entries created by that run.
To bring the whole preview environment back in line with the latest `master`:
1. Mark every run as merged or discarded and wait for active writes and indexing to finish.
2. Open **Contentful settings**.
3. Select **Recreate the environment** and confirm its ID.
pagent deletes its preview environment, copies the source environment again, and rebuilds the index. Field mappings and sync history remain. Recreating discards any unmerged work in the preview environment.
An environment that your team created and pagent reused is externally owned. pagent will not recreate or delete it. Manage that environment in Contentful, then refresh the index.
Disconnecting Contentful also leaves the preview environment in the space.
## Troubleshooting
Wait until the mapping screen stops saying that it is still matching. Then check these points:
* Refresh the index if the entry or field is new or renamed.
* Use the whole-space scope if the field sits outside the selected root entry's subtree.
* Select **Wrong target?** to use a ranked alternative, search by entry name, or browse by content type.
* Check that the destination field can hold the value. Text changes require a Symbol, Text, or Rich Text field. Image changes require an Asset link field.
* For an image from Contentful, check that the page URL still contains the source asset reference. pagent uses that reference for an exact match before it tries contextual matching.
* If the value is hard-coded in the website rather than stored in Contentful, skip it. The change continues through pagent's SDK.
If identical text appears in several entries, pagent can propose several targets. Remove any field that should not receive the change before confirming.
The locale list comes from the indexed preview environment. Check that the exact locale exists there, then refresh the index. pagent drops a previously saved locale if it no longer exists in the environment.
If the locale exists only in `master` because it was added after the preview environment was created, finish or resolve current runs and recreate the preview environment from `master`.
A separate rule applies to fields. If a field is not localized in its content type, pagent writes only the default locale even when the run includes several locales.
Large spaces can take several minutes. Check whether the processed entry count or last-update time is moving. You can leave the page while it runs.
A running index is marked stuck after 15 minutes without a heartbeat. A queued nightly index is allowed up to three hours because nightly work is staggered. pagent blocks another manual run while the current run is active. When pagent marks the run as stuck, select **Start indexing again**. The new run starts from the top and keeps the existing cached entries while it rebuilds.
If the panel says **failed**, use **Retry index**. Reconnect Contentful first if the message says access was rejected. If the preview environment itself failed or is missing, retry or recreate that environment before indexing.