# Gitea Actions Integration

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

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 Gitea

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)

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2FshysUoiyzgoQPdYJragH%2Fimage.png?alt=media&#x26;token=005d6556-a635-4a05-bd78-91cb0064e27c" alt=""><figcaption></figcaption></figure>

For example, to register the API token as a secret named `XYGENI_TOKEN`, for repository in the current working directory.

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

In a Gitea workflow (`.gitea/workflows/*.yml`) the Xygeni scanner could be run on the repository files, typically after `actions/checkout` to retrieve the branch sources.

You can configure a simple Gitea action with this workflow:

```yaml
name: Xygeni Scan
on:
  workflow_dispatch:

jobs:
  xygeni-scan:
    name: Xygeni Scan
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6.0.1
        with:
          repository: {ORG}/{REPO}
          token: ${{ secrets.GITEA_TOKEN }}
          # The default depth of 1 commit is not enough for some scans
          fetch-depth: 0

      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'

      - name: Xygeni-Scanner
        uses: xygeni/xygeni-action@v5.38.0
        with:
          token: ${{ secrets.XYGENI_TOKEN }}
          gh_token: ${{ secrets.POWER_GITEA_TOKEN }}
```

Where `XYGENI_TOKEN` is the name of the encrypted secret where the API token was saved. By default this action runs manually ***on: workflow\_dispatch.***

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2F1wDOTd3tUKk5fuK865ax%2Fimage.png?alt=media&#x26;token=1059d839-dc4f-42da-9fc1-1288240c7489" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Our scanner performs checks to recover information about your Gitea repository, 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>

The Xygeni API token is required.

| Parameter              | Description                                                                          | Mandatory | Default value                    |
| ---------------------- | ------------------------------------------------------------------------------------ | --------- | -------------------------------- |
| token                  | Xygeni API token                                                                     | Yes       |                                  |
| gh\_token              | Gitea token to retrieve repository information for misconfigurations and compliance. | No        | `GITEA_TOKEN`                    |
| command                | Command to execute by the scanner                                                    | No        | `scan --never-fail`              |
| 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 }}
      # No specific Gitea token needed for secrets and IaC scans
      # gh_token: ${{ secrets.POWER_GITEA_TOKEN }}
      command: scan -n ${{ gitea.repository }} -d /app --run=secrets,iac --fail-on=critical
```

Note that for secrets and iac scans, the default `GITEA_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 %}