GitHub Actions to Salesforce with JWT

Set up once

1. ECA with JWT bearer in the target org: Enable JWT Bearer Flow, upload server.crt, Permitted Users = Admin approved users are pre-authorized, and pre-authorize a dedicated deploy user's permission set (guides/auth/server-to-server-from-typescript.md). The deploy user needs a full Salesforce licence: an API-only integration licence generally can't deploy flows, permissions or Apex (reference/dx/deploy-errors.md).
2. GitHub secrets (never in the repo):

• SF_JWT_KEY: the contents of server.key;
• SF_CLIENT_ID: the consumer key;
• SF_USERNAME: the deploy user;
• SF_INSTANCE_URL: the My Domain URL.

The workflow

name: salesforce
on:
  pull_request:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      SF_DISABLE_TELEMETRY: "true"
      SF_AUTOUPDATE_DISABLE: "true"
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm install --global @salesforce/cli
      - name: Log in with JWT
        run: |
          echo "${{ secrets.SF_JWT_KEY }}" > server.key
          sf org login jwt --username "${{ secrets.SF_USERNAME }}" --jwt-key-file server.key \
            --client-id "${{ secrets.SF_CLIENT_ID }}" --instance-url "${{ secrets.SF_INSTANCE_URL }}" --alias target
          rm server.key
      - name: Validate (pull requests)
        if: github.event_name == 'pull_request'
        run: sf project deploy validate --manifest manifest/package.xml --test-level RunLocalTests --target-org target
      - name: Quick deploy the validated job (main)
        if: github.event_name == 'push'
        run: sf project deploy quick --use-most-recent --target-org target || sf project deploy start --manifest manifest/package.xml --test-level RunLocalTests --target-org target

The quick deploy reuses the most recent validation, which is valid for 10 days. If there isn't one, or it has expired, the fallback runs a full deploy with tests. The hub's reading: --use-most-recent picks the org's latest validation, which may not be the merged commit's. Teams that merge often should pass the PR's job ID (--job-id) through an artifact instead.

Agents in CI

• Deploy actions (Apex, flows, prompt templates) before or with the agents that call them, using one manifest (reference/dx/agentforce-metadata-types.md).
• Agent tests (sf agent test run) need the agent published and activated in the target first. Their failed assertions exit 0, so gate on the results file (guides/agentforce/test-an-agent.md). In CI, "Tests Pass Locally but Fail" is usually a missing JWT login or an inactive agent.

Known-bad