Work Flows

    Local Flow

    Use this workflow when your changes live in your local Git repository. Copado works from your feature branch, and you push and submit from there. You can run each step with the Agentia CLI or, where available, with the Agentia IDE extension in VS Code or Cursor. It applies with or without AI skills.

    Steps

    1. Step 0. Before you start: Verify your Copado credentials and check the workflow used by the project. Optionally, lock the project to the local workflow to block cloud commands. Ensure your working tree is clean prior to activating, publishing, or submitting a story.
    2. Step 1. Find your user story: List assigned stories and select the one to work on.
    3. Step 2. Set Current Work: Set it as the active work item. Copado switches the repository to the feature branch (feature/<story-name>). Resolve any setup warnings if prompted.
    4. Step 3. Make your changes: Create or edit metadata using Salesforce CLI, VS Code, or your IDE, then stage and commit changes in Git.
    5. Step 4. Dependency calculation: Calculate dependencies to see what components are used or depended on.
    6. Step 5. Run the quality gates: Run tests locally (all tests or specific Apex test classes) before sending changes to Copado.
    7. Step 6. Publish your changes: Register commits in Copado and sync the feature branch.
    8. Step 7. Validate your story: Validate changes and open the merge request.
    9. Step 8. Promote and deploy: Perform promotion and deployment only after obtaining proper approval.

    Good to know

    • Always create and use commits through Git in this workflow. Don't use cloud commit commands here.
    • You must be on the story's feature branch, with at least one new commit compared to the base branch, before you publish.
    • The Publish to Copado, Validate and Promote & Deploy buttons only appear when a story is set as current.
    • The cloud commands (cloud set, cloud commit, cloud promote) belong to the cloud workflow. Don't use them here.

    Step 0. Before you start

    agentia auth get --cicd --json
    agentia cicd workflow get --json
    agentia cicd workflow set local

    The last command is optional. It locks the project to the local workflow, so cloud commands are blocked. The workflow lock is only available in the CLI.

    Step 1. Find your user story

    agentia cicd work list --assigned-to-me --json
    agentia cicd work get <story-id> --json

    Step 2. Set Current Work

    agentia cicd work set <story-id> --json

    Step 3. Make your changes

    git add .
    git commit -m "<message>"

    Step 4. Dependency calculation

    Pick one input mode:

    # A local file
    agentia cicd metadata dependency list --path force-app/main/default/classes/MyClass.cls --json
    # A named component
    agentia cicd metadata dependency list --metadata-type ApexClass --metadata-name MyClass --json
    # Everything changed on your branch (committed changes plus staged changes, not unstaged)
    agentia cicd metadata dependency list --from-changes --json

    Defaults: pipeline, source credential and source org come from your active story, then from your project defaults. Target org: add --target-org-id <id> to also get a STATUS column comparing against that org. It is never filled in for you. Output: the table shows each component, its relation (used by or dependant), its type and its status.

    Step 5. Run the quality gates

    agentia cicd work test --json
    agentia cicd work test --apex-test-classes=MyTest,OtherTest --json

    The second command runs only specific Apex test classes, which is faster.

    Step 6. Publish your changes

    agentia cicd work publish --json

    Step 7. Validate your story

    agentia cicd work submit --json

    Step 8. Promote and deploy

    agentia cicd work submit --deploy --json

    Cloud Flow

    Use this workflow when you want Copado to pick up your changes straight from the source environment (org). You don't need local Git. It applies with skills (Agent) or without skills (no Agent).

    Steps

    1. Step 0. Before you start: Check that your Copado credentials are configured and that the project is set to the cloud workflow. Optionally, lock the project to the cloud workflow, so local-workflow commands are blocked and the two workflows can't get mixed.
    2. Step 1. Find your user story: List the stories assigned to you, then open the one you want to work on.
    3. Step 2. Set Current Work for cloud delivery: Set the story as your active work item. This step is required. Copado prepares the story for cloud delivery and records it as your active story. Nothing changes in your Git repository.
    4. Step 3. Make your changes in the source environment: Create or edit your metadata in the story's source environment. Use Salesforce CLI, VS Code or the Salesforce UI.
    5. Step 4. Dependency calculation: Copado calculates dependencies each time you run the metadata dependency command, and the extension calls that same command when you ask it to. Copado returns what a component uses and what depends on it.
    6. Step 5. Commit your changes: Send your changes to Copado. Always set the metadata category (use SFDX for Salesforce metadata). You can commit several changes at once by passing a file. The command waits until the commit finishes. If it takes too long, check its progress. Don't send the commit again.
    7. Step 6. Validate your story: Validate your changes and open the merge request.
    8. Step 7. Promote and deploy: Only do this when you have approval to promote and deploy.

    Good to know

    • Quality gates run in the cloud if they are configured.
    • Don't run two commits for the same story at the same time.
    • Avoid --recreate-feature-branch unless you're sure. It can overwrite work already on the story's branch.
    • The commands work publish, work submit and work done belong to the local workflow. Don't use them here.

    Step 0. Before you start

    agentia auth get --cicd --json
    agentia cicd workflow get --json
    agentia cicd workflow set cloud

    The last command is optional. It locks the project to the cloud workflow.

    Step 1. Find your user story

    agentia cicd work list --assigned-to-me --json
    agentia cicd work get <story-id> --json

    Step 2. Set Current Work for cloud delivery

    agentia cicd cloud set <story-id> --json

    Step 3. Make your changes in the source environment

    No Agentia command. Use Salesforce CLI, VS Code or the Salesforce UI.

    Step 4. Dependency calculation

    Pick one input mode:

    # A local file
    agentia cicd metadata dependency list --path force-app/main/default/classes/MyClass.cls --json
    # A named component
    agentia cicd metadata dependency list --metadata-type ApexClass --metadata-name MyClass --json

    Defaults: pipeline, source credential and source org come from your active story, then from your project defaults. Target org: add --target-org-id <id> to also get a STATUS column comparing against that org. It is never filled in for you. Output: the table shows each component, its relation (used by or dependant), its type and its status.

    Step 5. Commit your changes

    agentia cicd cloud commit <story-id> --metadata-category SFDX --json

    To commit several changes at once, pass a file:

    agentia cicd cloud commit <story-id> --file <changes.json> --json

    To check progress if the commit takes too long (don't send the commit again):

    agentia cicd job get <execution-id> --json
    agentia cicd job log get <execution-id> --json

    Step 6. Validate your story

    agentia cicd cloud promote <story-id> --json

    This creates a promotion if the story isn't in one yet.

    Step 7. Promote and deploy

    agentia cicd cloud promote <story-id> --deploy --json