Put the gate on a pull request.

Set it up

1. 01

   Install the GitHub App

   Audn scans through a GitHub App called Audn Ethical Hacker Agent. Install it on the account or organisation that owns the repositories you want gated.

   Nothing changes inside the repository. There is no workflow file to add and no secret to set: GitHub notifies the App itself every time a commit lands, the same way CodeRabbit and Snyk work.

   Installing takes admin rights on the account you install onto; if you do not have them, send the install link to whoever does. Whichever repositories you pick, the selection can be changed later from the installation's own settings.

   While a scan runs, Audn takes a private copy of the commit into a working repository owned by Audn — not by you — deploys it to an isolated sandbox, attacks it there, and deletes both when the run ends. Your repository is never written to.

   Choose "Only select repositories", never "All repositories". Every pull request in every repository you grant starts a billable run — there is no per-repository switch inside Audn, so the install screen IS the control over what you spend. Grant the repositories you actually want gated and add more later.

   Install on selected repositories →
2. 02

   Get a gateway token and put runs on it

   A gateway token is the handle your prepaid runs hang off. Issue one on the billing page, then buy runs against it.

   One gated pull request is one run and costs $99. Asking for a rerun of the same commit costs another run, on purpose; a repeat trigger on a commit that has not changed does not.

   The token is shown once and stored only as a hash, so copy it when it appears. If you lose it, issue a new one — nobody at Audn can read it back to you. You only ever paste it into a repository secret if you use the optional Action below; the App path needs no secret in your repository at all.

   Issue the token before you open a pull request, so the first scan has something to spend.

   If the balance runs out, the gate still reports. It opens a check run titled "Out of scan credits" and blocks the pull request instead of scanning it, because a commit nobody looked at must not look like a clean one. If you see that title, top up and re-run the check.

   A check titled "Gateway token not configured" means something different: the App is installed but this installation is not linked to a token yet, so there is no account to bill the run to. Finish the setup page and re-run the check.

   Get a gateway token →
3. 03

   Open a pull request

   That is the setup finished. GitHub tells the App about every commit pushed to a gated repository, so the scan starts on its own.

   A check run named "Audn red-team gate" appears on the pull request within a few seconds and stays in progress while the agent works. A scan takes about two and a half hours, so expect the pull request to sit there for a while.

   When it finishes, the check run reports pass or fail and a summary comment lands on the pull request with what was found and where. Later runs edit that same comment rather than adding another one.

   Nothing is blocked yet. Until you add the rule in the next step, the check reports its verdict and the pull request can still be merged.

4. 04

   Make the check block a merge

   A check run reports; it does not stop anything until you require it. Require it with a repository ruleset, and pin it to this App.

   Both of those choices matter. A ruleset starts with an empty bypass list, where classic branch protection exempts repository admins by default. And an unpinned required check is only a name, which anyone with write access can report as passing.

   The click path is below, in the order it has to happen.

   Run one scan before you write the rule. GitHub only lists a check in the required-checks picker once it has completed in that repository within the last seven days, so on a fresh install "Audn red-team gate" is not offered yet and there is nothing to select.

   1. 1.Run one scan first. GitHub only offers a check in the required-checks picker after it has completed in that repository within the last seven days, so on a fresh install "Audn red-team gate" is not there yet.
   2. 2.In the repository, open Settings, then Rules, then Rulesets. Choose New ruleset, then New branch ruleset.
   3. 3.Give it a name and set Enforcement status to Active. A ruleset saved as Evaluate reports what it would have done and blocks nothing.
   4. 4.Under Target branches, add your default branch.
   5. 5.Tick "Require status checks to pass", then add "Audn red-team gate" from the picker.
   6. 6.Set that check's expected source to the Audn Ethical Hacker Agent app. Left unpinned, anyone with write access can report the same check name as passing.
   7. 7.Leave the Bypass list empty. It starts empty, which is the reason to use a ruleset here: classic branch protection lets repository admins merge past a failing check unless you turn that off.
   8. 8.Save the ruleset, then open a pull request and confirm the check now shows as Required.
5. 05

   Start a scan from a comment

   You can also start a run by commenting on the pull request; the commands are listed below. The scan uses whatever commit the branch points at when you comment, not the commit that opened it.

   Only people with write access to the repository can start a run this way. GitHub tells us the commenter's role and everyone else is ignored, so a comment from a stranger on a public repository cannot spend your balance.

   @audn_ai, @audn and /audn are accepted as well, in case you type one of those out of habit.

   @audn-ai

   Scan this pull request at the commit its branch points at right now.

   @audn-ai scan

   The same thing, spelled out. "@audn-ai run" also works.

   @audn-ai rerun

   Scan the same commit again and pay for it again. A plain scan of an already-scanned commit returns the run you have and costs nothing, so this is the way to ask for genuinely fresh results. Careful: the words rerun, rescan, again and fresh anywhere in the comment mean this, so "@audn-ai can you scan this again?" is a second charge rather than a repeat of the first.

   @audn-ai help

   Replies on the pull request with this list of commands and what each costs. No scan starts and nothing is charged.

6. 06

   Optional: start the scan from a workflow

   Most customers do not need this. The App already triggers on its own, and this Action does the same job from a workflow file.

   The reason to use it is the preview URL. If your CI deploys a preview of the pull request, the Action can hand Audn that URL and the agent attacks your running deployment instead of the sandbox copy Audn otherwise builds for itself.

   Store your gateway token as a repository or organisation secret named AUDN_GATEWAY_TOKEN, then add the file below. It needs no checkout step: Audn clones the commit itself.

   The workflow does not wait for the result. A scan takes about two and a half hours, and the App reports the verdict on the pull request anyway, so waiting would burn CI minutes for nothing. Set wait: true only if you want the job itself to hold and fail.

   One honest caveat: audn-ai/audn-gate-action is not published to the GitHub Marketplace yet, so this is the one step on this page you cannot finish on your own today. Email support@audn.ai and we will send you the reference to pin. Nothing above depends on it — the App triggers without any of this.

   yaml.github/workflows/audn-gate.yml

   Copy

   name: Audn gate (trigger)
   
   on:
     pull_request:
       types: [opened, synchronize, reopened]
   
   permissions:
     contents: read
   
   jobs:
     audn:
       runs-on: ubuntu-latest
       steps:
         - name: Start Audn scan
           uses: audn-ai/audn-gate-action@v1
           with:
             token: ${{ secrets.AUDN_GATEWAY_TOKEN }}
             # wait:false starts the scan and returns; the App reports the verdict on the pull
             # request itself. Set wait:true (and fail-on) only to make this job hold and fail.
             wait: false

If something is not working