# Porticol in GitHub Actions

> Run Porticol collections in a GitHub Actions workflow, with JUnit reports and a failing job when a test fails.

Canonical: https://porticol.app/integrations/github-actions

`porticol-cli` runs a collection in a workflow, writes JUnit, JSON and HTML reports, and exits with a code the job acts on.

## Add the job to a workflow

```
env:
  PORTICOL_CLI_VERSION: 0.1.0
jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install porticol-cli
        run: |
          case "${{ runner.arch }}" in
            X64) platform=linux-x64 ;;
            ARM64) platform=linux-arm64 ;;
            *) echo "no porticol-cli for ${{ runner.arch }}" >&2; exit 1 ;;
          esac
          base="https://updates.porticol.app/$PORTICOL_CLI_VERSION"
          curl -fsSLO "$base/porticol-cli-$PORTICOL_CLI_VERSION-$platform.tar.gz"
          curl -fsSL "$base/SHA256SUMS" -o SHA256SUMS
          grep " porticol-cli-$PORTICOL_CLI_VERSION-$platform.tar.gz$" SHA256SUMS | sha256sum -c -
          tar -xzf "porticol-cli-$PORTICOL_CLI_VERSION-$platform.tar.gz" porticol-cli
      - run: ./porticol-cli run checkout.json -e staging.json --secret apiKey -r junit:report.xml
        env:
          apiKey: ${{ secrets.API_KEY }}
          PORTICOL_TOKEN: ${{ secrets.PORTICOL_TOKEN }}
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: api-tests
          path: report.xml
```

Keep `PORTICOL_TOKEN` in the repository's secrets, and pin `PORTICOL_CLI_VERSION` so a new release does not change what the job runs.

## What it can do

- Runs a collection, a flow or a performance run from a file, a Postman export, or a workspace read with an API token.
- Writes JUnit, JSON and HTML reports.
- Exits 0 when everything passed, 1 when a test or threshold failed, 2 when a request could not be made, and 3 when the job's own configuration is wrong.
- The binary is static, so it runs on any Linux of that architecture, Alpine included.
- A token needs Pro. A local run checks it once a day and keeps the check for 30 days offline.

## Try it

Commit a collection and its staging environment, add the job, and let a pull request fail when a test does.

## Questions

**Does a CI run need a person?**

No. It reads a collection file in the repository, or a workspace through an API token kept in the pipeline's secret store.

**Which plan does an API token need?**

Pro. A run without a token signs in with porticol-cli login instead.

## Try it on your own APIs

Free for one seat, on macOS, Windows and Linux.