Actagate
Sign in

For administrators

An organization owner or admin connects the GitHub App and registers repositories for requests. The person connecting it also needs administrator access to the target organization on GitHub. Complete the connection and registration, then check branch protection. The final section covers App creation for self-hosted deployments.

Install the GitHub App

  1. Open “Settings”, go to “Integrations” under “Organization settings” and choose “Connect GitHub App” on the GitHub card.
  2. Select the organization on GitHub.
  3. Choose Only select repositories and select the target repositories.
  4. Choose Install, complete user authorization, and return to Actagate.
  5. Check that the connected organization appears on the GitHub card.

The standard product App is Actagate (slug actagate, bot name actagate[bot]). The service operator owns one App, which fv also uses. Only self-hosted organizations create their own App.

Register repositories

Open “GitHub repositories” in settings and load repositories from the connected organization. Select a repository, enter its settings, and register it. If a repository was not selected during installation, add it to the App's access on GitHub first.

Field Value
Protected branches PR base branches accepted for requests. Default: main. Enter multiple branches on separate lines
Approval route JSON. null means the manager. Use manager, user, or usergroup
Merge mode The app merges, or approval check only
Merge method Repository default, merge, squash, or rebase
Precheck None or Terraform. Specify the comment author and heading, or the check run name
Watched workflow Workflow filename whose result is checked after merge. Leave empty for no monitoring
Watch timeout Minutes. Default: 30
Manual instructions Work for the operator when the API is unavailable
Risk rules Target paths in paths. Terraform destroy and replace operations also count

Saving replaces settings and the approval route. Include values you want to retain. Settings changes and removal of registrations are audited.

Check branch protection

Choose “Check branch protection” on a registered repository. The result shows protection and required checks for each protected branch. If you registered a pattern such as release/*, also check protection on individual branches on GitHub.

For repositories that support branch protection, edit protection for the target branch in GitHub repository settings. Enable Require status checks to pass before merging, require the Actagate / approval check, and save. For your own App, select the approval check using that deployment's app display name. If the check is absent from the list, check again after a request creates it.

A GitHub 403 response displays guidance that protection is unavailable. Check the App's Administration permission as well as plan restrictions. If retrieval fails, inspect the settings directly on GitHub.

Configure workflows without branch protection

Choose the mode where the app merges, and check the actor at the start of the deployment job. This example uses the standard App. Change the bot name for your own App.

on:
  push:
    branches: [main]
  workflow_dispatch:
    inputs:
      request_id:
        description: 'Approval request ID'
        required: true
        type: string
jobs:
  apply:
    runs-on: ubuntu-latest
    steps:
      - name: Require approved merge
        if: github.event_name == 'push' && github.actor != 'actagate[bot]'
        run: exit 1
      - name: Record manual request
        if: github.event_name == 'workflow_dispatch'
        run: |
          REQUEST_ID=$(jq -er '.inputs.request_id' "$GITHUB_EVENT_PATH")
          test -n "$REQUEST_ID"
          printf 'Approval request %s\n' "$REQUEST_ID"
      # Place checkout, validation and deployment steps here.

The actor condition for pushes is if: github.actor != 'actagate[bot]'. The example also checks the event name to allow the manual path separately. A direct push to main by a person fails this job. The change remains on main and will be applied together with the next approved merge. This does not prevent direct pushes or merges.

When a person merges in copy mode, compare the PR with the approved head SHA. Enter the request ID when starting workflow_dispatch, then record the merge commit SHA and run URL as request evidence. A required input does not make GitHub verify that the request was approved. The operator must check the request and SHA.

Create an App for a self-hosted deployment

Create a GitHub App in GitHub Developer settings.

  1. Choose a name and set Homepage URL to the deployment's public URL.
  2. Register exactly one Callback URL: https://<app host>/api/settings/github/callback. Do not use Setup URL.
  3. Enable Request user authorization (OAuth) during installation. Disable Webhook.
  4. Choose Any account for installation access.
  5. Set these seven Repository permissions.
Repository permission Access
Metadata Read
Contents Read and write
Pull requests Read and write
Checks Read and write
Actions Read
Commit statuses Read
Administration Read

Generate a Client secret and private key, then configure these five deployment variables. Do not paste secrets into the repository or request evidence.

Environment variable Value
GITHUB_APP_ID App ID
GITHUB_APP_CLIENT_ID Client ID
GITHUB_APP_CLIENT_SECRET Client secret
GITHUB_APP_PRIVATE_KEY PEM private key. Use line breaks or \n
GITHUB_APP_SLUG App slug

After configuration, follow the installation steps above. If the return fails, ask the operator to check Callback URL, the public URL, and OAuth on install.

Open on docs.actagate.com