GitHub Actions Integration

SCC CLI integrates with GitHub Actions for automated configuration validation and AI coding governance.

Basic Setup

.github/workflows/scc-validate.yml

name: SCC Validation
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install uv
        run: |
          curl -LsSf https://astral.sh/uv/install.sh | sh
          echo "$HOME/.local/bin" >> $GITHUB_PATH
          echo "$HOME/.cargo/bin" >> $GITHUB_PATH

      - name: Install SCC
        run: uv tool install scc-cli

      - name: Configure SCC
        run: scc setup --org "$SCC_ORG_SOURCE" --auth env:SCC_ORG_TOKEN --team ci --non-interactive
        env:
          SCC_ORG_SOURCE: ${{ secrets.SCC_ORG_SOURCE }}
          SCC_ORG_TOKEN: ${{ secrets.SCC_ORG_TOKEN }}

      - name: Validate configuration
        run: scc start --dry-run --json --non-interactive --team ci .

Required Secrets

Add these secrets to your repository (Settings → Secrets):

Secret	Description
SCC_ORG_SOURCE	URL or shorthand for your org config
SCC_ORG_TOKEN	Auth token for private configs (if needed)

Workflow Examples

Validate on Pull Request

name: Validate SCC Config
on:
  pull_request:
    paths:
      - '.scc.yaml'
      - 'team-config.json'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Install SCC
        run: pip install scc-cli
      - name: Validate team config
        run: scc team validate --file team-config.json

Audit Plugins

name: Weekly Plugin Audit
on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9am

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Install SCC
        run: pip install scc-cli
      - name: Configure SCC
        run: scc setup --org "$SCC_ORG_SOURCE" --non-interactive
        env:
          SCC_ORG_SOURCE: ${{ secrets.SCC_ORG_SOURCE }}
      - name: Audit plugins
        run: scc audit plugins --json

Cache Configuration

Speed up workflows by caching SCC configuration:

- uses: actions/cache@v4
  with:
    path: ~/.cache/scc
    key: scc-cache-${{ hashFiles('**/org-config.json') }}
    restore-keys: |
      scc-cache-

Exit Codes

Use exit codes for conditional workflow logic:

Code	Meaning	Action
0	Success	Continue
2	Usage error	Check command syntax
3	Configuration error	Fix config files
6	Governance block	Review policy violations

- name: Check validation result
  run: |
    scc start --dry-run --non-interactive --team ci .
    exit_code=$?
    if [ $exit_code -eq 6 ]; then
      echo "::error::Configuration blocked by governance policy"
      exit 1
    fi

CI-Specific Team Profile

Create a minimal profile for CI environments:

{
  "profiles": {
    "ci": {
      "description": "CI/CD pipeline profile",
      "additional_plugins": [],
      "session": {
        "timeout_hours": 1
      },
      "network_policy": "isolated"
    }
  }
}

Tip

CI profiles typically need fewer plugins and shorter timeouts than developer profiles.

Security Best Practices

• Never expose secrets in logs: Use GitHub’s secret masking
• Use minimal permissions: CI profiles should be restrictive
• Validate before merge: Catch config issues in PRs
• Review JSON output: Parse --json output for detailed validation results

Danger

Never commit org config sources or tokens to your repository. Always use GitHub secrets.

Troubleshooting

”Command not found: scc”

Ensure $HOME/.local/bin is in PATH after installing with uv:

- name: Install uv
  run: |
    curl -LsSf https://astral.sh/uv/install.sh | sh
    echo "$HOME/.local/bin" >> $GITHUB_PATH

“Cannot connect to Docker daemon”

For dry-run validation, Docker isn’t required. For actual sessions, ensure your runner has Docker:

runs-on: ubuntu-latest  # Has Docker pre-installed

“Governance block” exit code

Your configuration violates org policies. Run scc config explain locally to see what’s blocked.

Next Steps

CI/CD Automation Guide Complete CI/CD integration guide

GitLab CI GitLab CI integration

CLI Reference Full command reference