Quick start

1. Your First User Story

Pick or create a User Story in Copado and start working on it from your development environment.

1.1 Find an existing story

agentia cicd work list --assigned-to-me
agentia cicd work list --status "In Progress" --project-name MyProject
agentia cicd work get US-0001

Note the story Id (a0S...) or name (US-0001). You can use either in later commands.

1.2 Or create a new story

agentia cicd work create \
  --title "Add SLA field to Account" \
  --project <project-id> \
  --team <team-id> \
  --assignee <user-id> \
  --acceptance-criteria "Account page shows SLA__c -> open an Account -> field is visible"

Tips:

• Save your project, team, and assignee once so you can omit them next time:

  agentia cicd project default set --project <project> --team <team> --assign-me
  

• --acceptance-criteria must be under 255 characters.

• Add --json to any command for machine-readable output.

1.3 Start working on the story

agentia cicd work set US-0001

This command:

• Reads the story and the pipeline settings.
• Fetches the base branch and any existing remote feature branch.
• Creates or checks out feature/<story-name>.
• Records the story as your active story, so later commands need no story argument.

Before you run it: your tracked working tree must be clean.

If you see a warning about a missing pipeline or credential, fix the story's pipeline or source credential in Copado (or with agentia cicd work update --source-credential ...) before you publish or submit.

You can switch the base branch with --base-branch <branch>. Run agentia cicd work set --none to clear the active story.

1.4 (Optional) Move the story forward

agentia cicd work update US-0001 --status "In Progress"

Checkpoint: git branch --show-current prints feature/<story-name>.

---

2. Develop and Validate Salesforce Changes Locally

Build your changes with your coding agent and validate them against your Salesforce org.

2.1 Build with your coding agent

Open the repository in your agent and describe the change. For example: "Add an SLA__c picklist on Account and a Apex trigger that defaults it. Include tests."

To help the agent, you can:

• Ask it to read org metadata first: agentia cicd metadata explore (see --help) or agentia cicd metadata list.
• Point it to the active story: agentia cicd work status and agentia cicd work get.

2.2 Deploy against your Dev org

Use standard Salesforce CLI commands, or the agent's Salesforce tooling.

# Push your source changes to the Dev org
sf project deploy start --target-org my-dev

2.3 Run local quality gates

# Run the project's quality gates; if none exist, it runs the stock Apex sample
agentia cicd work test

# Faster: run only specific Apex test classes
agentia cicd work test --apex-test-classes=AccountSlaTest,AccountServiceTest

# Re-run only the classes that failed last time
agentia cicd work test --rerun-failed-apex-tests

Quality gates are scripts at the project root: .agentia_quality_gates.sh (macOS/Linux) or .agentia_quality_gates.cmd (Windows).

You can also run Apex tests directly:

agentia cicd work test apex -t AccountSlaTest

Failed runs are saved in .agentia/apex.tests.<story>.json and removed after a passing run.

2.4 Commit locally and register the commit

Commit with Git, then register the commit in Copado with Agentia.

git add -A
git commit -m "US-0001 Add SLA field and defaulting trigger"

# Optional preview: nothing is pushed or registered
agentia cicd work publish --dry-run

# Push the feature branch and register the commits on the story
agentia cicd work publish

work publish does the following:

• Pushes feature/<story-name>.
• Applies Copado environment-variable and YAML replacements.
• Registers the commits and the changed metadata on the story.
• Merges the feature branch into the Dev environment branch.

A plain git push does not register anything in Copado. Always finish with work publish.

If a profile or permission set changes in a way that automatic nested detection misses, add one of these:

agentia cicd work publish --permissions CustomField:Account.SLA__c
agentia cicd work publish --full-metadata PermissionSet:Sales_Onboarding

Notes:

• The working tree must be clean before you publish.
• No changes to publish means there are no new commits since the base branch.

Checkpoint: tests pass, git status is clean, and work publish finishes without errors.

---

3. Commit and Promote Changes Through the Pipeline

3.1 Submit for validation

agentia cicd work submit

Submit does the following:

• Runs local quality gates (skip with --skip-local-tests).
• Pushes and registers any unpublished commits.
• Starts a Copado validation against the next environment.
• Opens the merge-request page (skip with --skip-pull-request).

3.2 Check job status

Validation runs asynchronously.

agentia cicd work status

If a job fails, fix the issue, git commit, run agentia cicd work publish, then agentia cicd work submit again.

3.3 Handle "stories behind" warnings

If submit warns that other stories are ahead in the destination environment, sync first.

agentia cicd work environment-sync --destination-environment dev1

# If it stops on merge conflicts: resolve the files, then continue (or abort)
agentia cicd work environment-sync --continue
agentia cicd work environment-sync --abort

3.4 Promote and deploy

When validation is green and your merge request is approved:

agentia cicd work submit --done

This promotes the story and deploys it to the next environment in the pipeline. agentia cicd work done is an alias.

Confirm the result:

agentia cicd work status
agentia cicd promotion list
agentia cicd work open        # open the story in Copado

If the promotion has conflicts, use agentia cicd promotion conflict list and agentia cicd promotion conflict resolve <id>.

Checkpoint: the promotion shows Completed, and the story is in the next pipeline environment.

---

Cheat sheet

Goal	Command
Find a story	agentia cicd work list --assigned-to-me
Create a story	agentia cicd work create --title "..."
Start work	agentia cicd work set <story>
Test locally	agentia cicd work test
Commit	git commit, then agentia cicd work publish
Validate	agentia cicd work submit
Promote and deploy	agentia cicd work submit --done
Check jobs	agentia cicd work status

Troubleshooting

Symptom	Fix
set fails on a dirty tree	Commit or stash tracked changes, then re-run.
Warning about no pipeline or credential	Fix the story's project, pipeline, or source credential in Copado.
No changes to publish	Commit your work first, or pass --permissions or --full-metadata.
Submit warns of stories behind	Run agentia cicd work environment-sync.
Auth errors	Run agentia auth get, then agentia auth set --cicd <key> --region <region>.

Do not mix flows

This guide uses the local Git flow. Do not use agentia cicd cloud commit or agentia cicd cloud promote on the same story.