# GitHub Actions Integration

### Introduction <a href="#introduction" id="introduction"></a>

[GitHub Actions](https://docs.github.com/en/actions) is a platform for continuous integration in GitHub repositories. An action encodes a reusable task with configurable parameters.

Xygeni provides a `xygeni-action` for downloading and running the scanner on the repository.

{% hint style="info" %}
The following configuration examples show how to install & run the scanner using an API Token stored as a secret named `XYGENI_TOKEN`. See [Generate Xygeni API Token for Scanner](https://docs.xygeni.io/xygeni-administration/profile#generate_token_for_scanner-1) or ask your Xygeni administrator to generate it.
{% endhint %}

### Usage

The `xygeni-action` action downloads, configures and executes the Xygeni Scanner on the repository where the action is invoked.

#### Setting API token as encrypted secret in GitHub

The scanner needs an **API token** to communicate with the Xygeni platform. Such API token is a secret that could be registered safely at the appropriate scope (organization, repository or environment) using [GitHub Encrypted Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets).

<br>

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2FLA6imyNZtkKgVa1biqxd%2Fimage.png?alt=media&#x26;token=a9e06888-7275-48f9-9cdf-0c7afb66c976" alt=""><figcaption></figcaption></figure>

For example, to register the API token as a secret named `XYGENI_TOKEN`, for repository in the current working directory. you may use the GitHub `gh` command:

```bash
# The command will prompt you to enter the secret value
gh secret set XYGENI_TOKEN

# Alternatively you may read the value of the API token from a local file
gh secret set XYGENI_TOKEN < /path/to/xygeni_token.txt
```

(You must be the repository owner for creating repository secrets.)

For creating encryption secret at environment scope in a personal account repository (you need to be the repository owner), add `--env ENV_NAME`:

```shell
# Set the secret available to private repositories only
gh secret set --env ENV_NAME XYGENI_TOKEN
```

For creating encryption secret at organization scope (so the secret is available to all or a subset of the organization repositories), add `--org ORG_NAME`:

```shell
# GitHub CLI does not have admin:org permission by default
gh auth login --scopes "admin:org"

# Set the secret available to private repositories only
gh secret set --org ORG_NAME XYGENI_TOKEN

# Or set the secret available to all organization repositories
gh secret set --org ORG_NAME XYGENI_TOKEN --visibility all

# Or limit visibility of the secret to the selected repos
gh secret set --org ORG_NAME XYGENI_TOKEN --visibility all
```

You may use the corresponding GitHub webpages for setting the api token as a secret named `XYGENI_TOKEN` at the appropriate scope.

#### Add a step calling the action <a href="#add_a_step_calling_the_action" id="add_a_step_calling_the_action"></a>

In a GitHub workflow (`.github/workflows/*.yml`) the Xygeni scanner could be run on the repository files, typically after `actions/checkout` to retrieve the branch sources. The `GITHUB_WORKSPACE` environment variable will contain the default location of the repository when using the checkout action.

You can configure a GitHub action with the form:

```yaml
on:
  workflow_dispatch:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  xygeni-scan:
    runs-on: ubuntu-latest
    name: xygeni-github-action
    steps:
      # Checkout the repository sources (GITHUB_WORKSPACE)
      - name: Checkout
        # You may instead pin to an action SHA
        uses: actions/checkout@v6.0.1
        with:
          # The default depth of 1 commit is not enough for some scans
          fetch-depth: 0

      - name: Xygeni-Scanner
        uses: xygeni/xygeni-action@5.38.0
        id: Xygeni-Scanner
        with:
          # The xygeni api token
          token: ${{ secrets.XYGENI_TOKEN }}
          # Checking the GitHub configuration requires a token with sufficient permissions.
          # The default token (GITHUB_TOKEN) does not have enough permissions.
          gh_token: ${{ secrets.GH_PAT }}
```

Where `XYGENI_TOKEN` is the name of the encrypted secret where the API token was saved.

{% hint style="info" %}
Our scanner performs checks to recover information about your GitHub repository and organization, as part of the scanning process to validate if there are misconfigurations affecting them.

See [Required token permissions](https://docs.xygeni.io/xygeni-scanner-cli/xygeni-cli-overview/scm-ci-cd-and-container-registry-tokens#required-token-permissions) for further details.
{% endhint %}

#### Parameters <a href="#parameters" id="parameters"></a>

Only the API token is required.

The default values for some parameters can be changed. For example, you may specify a specific name for the project instead of the GitHub repository name,`GITHUB_REPOSITORY`. Also, you may want to scan a particular source subdirectory instead of the default.

You can see more information about default GitHub environment variables [here](https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables).

The available parameters for the action are:

| Parameter              | Description                                                                           | Mandatory | Default value                    |
| ---------------------- | ------------------------------------------------------------------------------------- | --------- | -------------------------------- |
| token                  | Xygeni API token                                                                      | Yes       |                                  |
| command                | Command to execute by the scanner                                                     | No        | `scan --never-fail`              |
| gh\_token              | GitHub token to retrieve repository information for misconfigurations and compliance. | No        | `${GITHUB_TOKEN}`                |
| xygeni\_url            | Base URL of the Xygeni API                                                            | No        | `https://api.xygeni.io`          |
| xygeni\_dashboard\_url | Base URL of the Xygeni Dashboard                                                      | No        | `https://in.xygeni.io/dashboard` |

{% hint style="info" %}
Use `--never-fail` to avoid breaking the build if the scan finds issues or fails.\
\
You may also use `--fail_on=critical` to terminate the build only when critical issues are found.
{% endhint %}

{% hint style="info" %}
Use `--run=secrets,iac` if you want to scan only for secrets and IaC flaws, for example.
{% endhint %}

{% hint style="info" %}
If you want to analyze a subdirectory, you can configure the command with `-d` parameter. For example, use `-d /app` if the directory to scan is the `app` directory in your repository.
{% endhint %}

Example for scanning only hard-coded secrets and IaC flaws detectors, and failing the build only when critical issues are found:

```yaml
  - name: Xygeni-Scanner
    uses: xygeni/xygeni-action@v5.38.0
    id: Xygeni-Scanner
    with:
      token: ${{ secrets.XYGENI_TOKEN }}
      command: scan -n ${{ github.repository }} -d /app --run=secrets,iac --fail-on=critical
```

Note that for secrets and iac scans, the default GITHUB\_TOKEN has enough permissions.

See [Xygeni scan command](https://docs.xygeni.io/xygeni-scanner-cli/xygeni-cli-overview/xygeni-cli-operation-modes/single-scan) for full information on the `command` options available.

{% hint style="info" %}
You may use pinned versions for the action, using the immutable commit SHA instead of version numbers, as specified in [Pin actions to full length commit SHA](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-third-party-actions).
{% endhint %}