Promote a Copilot Agent Across Environments with WIQD

The HR policy agent worked perfectly for its developer. Then the release manager asked four excellent questions: Which package did you test? Which SharePoint library does it read? Who can discover it? And, just for fun, are you signed into the right tenant?

That is the moment agent development becomes agent delivery. Work IQ Developer Tools (WIQD) keeps package, provision, and share separate so one click cannot accidentally turn a development build into a tenant-wide incident. Let us promote the same validated HR policy agent from a developer-only deployment to a pilot mail-enabled security group, while development reads a test library and the pilot reads an approved, read-only library.

Package, Provision, and Share Are Different Gates

These operations sound interchangeable until the wrong one succeeds:

Operation	What changes	Blast radius	Evidence to keep
Package	Creates an immutable .zip from validated source	A file on disk	Version, SHA-256 checksum, contents
Provision	Creates or updates a deployment in one named environment	One deployment identity in one tenant	Environment, app ID, tenant, deep link
Share	Grants an audience access to an existing deployment	Selected users, a group, or the tenant	Deployment, audience, approver, confirmation

Packaging does not deploy. Provisioning does not grant a pilot access. Sharing does not rebuild the package. That separation is the safety model: prove the artifact once, apply named configuration deliberately, and expand the audience only after inspecting the resulting deployment.

Build an Explicit Environment Matrix

Start by reviewing every file under env/. Commit identifiers, URLs, display names, and non-sensitive feature settings. Keep credentials and tokens in .env.<environment>.user files locally or inject them from your CI secret store. The .user files must remain ignored.

Setting	dev	test pilot	Commit?
Tenant ID	00000000-…-dev	00000000-…-test	Yes, if your policy allows tenant IDs
Agent name	HR Policy Agent (Dev)	HR Policy Agent (Pilot)	Yes
Policy library	https://contoso.sharepoint.com/sites/hr-dev/policies	https://contoso.sharepoint.com/sites/hr-approved/policies	Yes
API endpoint	https://hr-api-dev.contoso.com	https://hr-api-test.contoso.com	Yes
Auth registration ID	Dev registration placeholder	Test registration placeholder	Yes
Client secret/token	Injected locally	Injected by release pipeline	Never
Sharing audience	Developer only	[email protected]	Yes, as release intent

The auth registration belongs in the matrix because it is easy to promote a correct endpoint with the wrong OAuth client. Treat tenant ID, app ID, auth registration, and endpoint as one environment identity. If any one points somewhere else, stop.

env/
├── .env.dev
├── .env.dev.user       # secrets; gitignored
├── .env.test
└── .env.test.user      # secrets; gitignored

Validate Once, Then Seal the Package

Run deep validation and a smoke-sized eval set before packaging. Do not package first and promise to test that zip later. The artifact receives its identity only after the quality gate passes.

wiqd agent validate --mode deep
wiqd agent eval --env dev
wiqd agent package

# Use the package path printed by WIQD.
PACKAGE="appPackage/build/hr-policy-agent.zip"
zipinfo -1 "$PACKAGE" | sort
sha256sum "$PACKAGE"

The package listing should contain the app manifest, declarative agent manifest, instructions, icons, and referenced plugin files. It must not contain env/, .env*, .user files, eval results, source-control metadata, or local logs. Check rather than assume:

if zipinfo -1 "$PACKAGE" | grep -Ei '(^|/)(\.env|env/|.*\.user$|\.git/|logs?/|eval-results/)'; then
  echo "STOP: local configuration found in package" >&2
  exit 1
fi

Record the checksum beside the release version in your release evidence, not inside the zip. For example:

artifact: hr-policy-agent.zip
version: 1.4.0-rc.2
sha256: 8f3c…c92a
validation: clean
eval smoke: 8/8 passed

From this point forward, a source edit or a second wiqd agent package creates a different candidate. If the checksum changes between development and test, that is not promotion. It is a new release, and it goes back through validation and evals.

Provision Development and Test Deliberately

Ask WIQD to provision the recorded package to dev, then test, using each named environment’s configuration. Do not copy values between files during the release. The environment is the input; the package stays the invariant.

After confirmation, capture the deployment metadata and run the same smoke prompts that passed before packaging. Repeat for test, but expect the approved policy library and test auth registration in the inspection.

Environment	Package SHA-256	Deployment identity	Policy source	Deep link	Smoke
dev	8f3c…c92a	HR Policy Agent (Dev) / app-dev-…	Dev policy library	Saved from provision output	Pass
test	8f3c…c92a	HR Policy Agent (Pilot) / app-test-…	Approved read-only library	Saved from provision output	Pass

Open each newly returned deep link and verify the displayed agent name before bookmarking it. A saved link can point to a stale deployment even when today’s provision succeeded.

Share the Test Deployment, Not the Project

Now invoke WIQD’s guided share flow for test. Sharing should begin with project and deployment inspection, not an audience picker.

If the address does not resolve, resolves to a distribution list you did not approve, or is not the expected mail-enabled security group, cancel. Fix the group in Exchange or choose verified individual users; do not “temporarily” switch to tenant scope. Microsoft documents how to manage mail-enabled security groups and how the available Microsoft 365 group types differ.

The three audience scopes have very different consequences:

• User is best for a release manager or one acceptance tester.
• Group is best for a controlled pilot whose membership has an owner and review process.
• Tenant makes the deployment available organization-wide and belongs after pilot evidence, governance review, and the required admin approval—not before.

Verify Both Sides of the Boundary

Successful sharing output proves that a permission operation completed. It does not prove the boundary is correct. Test with two real accounts:

Verification account	Group membership	Expected result
Pilot user	Included	Can open the current test deep link, discover the pilot agent, and complete smoke prompts
Control user	Excluded	Cannot discover or open the pilot deployment

Record the account, time, deployment ID, and result. Also verify that the included user sees only documents they already have permission to read. Agent distribution never replaces SharePoint or API authorization.

Operate the Deployment After Release

Write down ownership before the pilot starts:

• Update: rebuild only after source changes, validate again, record a new checksum, provision to development, then promote.
• Rollback: re-provision the last approved package checksum and repeat both access checks. Never rebuild an old Git tag and assume the bytes match.
• Unshare: use WIQD’s guided sharing workflow to remove the pilot audience, confirm the exact test deployment, and verify the former member loses discovery and access.
• Delete: remove the deployment only after it is unshared and its deep link and deployment ID are recorded. Deleting test must not delete development, its app registration, or the source package.

The release manager owns promotion evidence and audience approval. The developer owns validation and package contents. The environment owner owns registrations and secrets. The group owner owns membership. Somebody specific—not “the team”—owns rollback and deletion.

Publish the Approved Version Across the Tenant

A successful pilot is not the global release. Sharing the test deployment proves the package with a controlled audience; publishing hands the approved production package to Microsoft 365 administrators for organization-wide deployment.

Create the production candidate from the same reviewed source, increment the app version, validate it, and record its checksum. Then submit that package to your organization’s app catalog. In the Microsoft 365 Admin Center, an administrator opens Settings > Integrated Apps, reviews the agent’s permissions and data access, approves the new version, and deploys it to Everyone or to the organization-wide groups defined by policy.

Publish with the WIQD CLI

Sign in to the production tenant, run the publishing readiness pipeline without submitting anything, inspect its report, and only then publish:

wiqd auth status
wiqd auth login --interactive

wiqd agent publish --env prod --dry-run --browser
wiqd agent publish --env prod

The dry run validates the manifests, checks referenced URLs, samples the deployed agent, and opts into browser checks. Treat a failure as a release blocker. The final command submits the production package to the organization catalog; it does not bypass administrator approval or deploy the agent to everyone.

Publish Agentically with a Coding Agent

Install the WIQD plugin once for your coding-agent CLI:

wiqd component plugin install --cli copilot

Then ask the coding agent for the outcome instead of translating the release process into commands yourself:

The coding agent is driving the same WIQD readiness and publish workflow as the CLI. Agentic does not mean autonomous approval: it means the agent gathers the evidence, stops at the consequential boundary, and continues only after an authorized human confirms.

Before the administrator confirms deployment, the release record should connect every boundary:

Release evidence	Required match
App identity	Same approved agent identity; no accidental second listing
Version	New production version shown in the package and Admin Center
Package checksum	Exact checksum from the final validation and eval run
Environment	Production tenant, endpoints, registrations, and data sources
Permissions	No scopes or capabilities beyond those approved during review
Audience	Everyone or the explicitly approved organization-wide groups

After deployment, verify the new version with an included production user and confirm the Admin Center reports the intended audience. Keep the pilot deployment available until that check passes so rollback remains a deliberate switch to the previous approved package, not an emergency rebuild.

That is the whole promotion path: one validated package moves through named deployments and a deliberately small audience, then its approved production version crosses the administrative gate for tenant-wide deployment. Packaging creates the thing. Provisioning chooses where it runs. Sharing proves it with a pilot. Publishing decides which version the organization receives.

The Value You Just Unlocked

• One artifact with a verifiable history: Checksums connect validation, pilot evidence, admin review, and production deployment to the package you actually tested.
• Environment changes without source drift: Named configuration moves the same agent behavior from development to test and production while keeping tenant-specific resources explicit.
• A controlled pilot boundary: Group sharing proves real-user behavior and access before the release reaches the broader organization.
• An administrative last mile: Microsoft 365 administrators review permissions, approve the version, and assign the global audience in the Admin Center.
• A rollback you can execute: Recorded package versions, deployment identities, and audience decisions make recovery a known operation instead of a rebuild under pressure.

You have moved agent delivery from “it works in my tenant” to a release process with evidence at every gate. The result is not merely a deployed agent; it is a version your developers, release managers, and administrators can all identify, approve, and operate.

Resources

• Work IQ Dev Tools quickstart
• Work IQ Dev Tools agent lifecycle
• Work IQ Dev Tools environments
• Work IQ Dev Tools CLI reference
• Provision cloud resources with Microsoft 365 Agents Toolkit
• Publish agents for Microsoft 365 Copilot
• Manage Copilot agents in the Microsoft 365 admin center
• Manage mail-enabled security groups in Exchange Online
• Publishing and governing declarative agents