Connect GitHub
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
Section titled “Install the GitHub App”- Open “Settings”, go to “Integrations” under “Organization settings” and choose “Connect GitHub App” on the GitHub card.
- Select the organization on GitHub.
- Choose Only select repositories and select the target repositories.
- Choose Install, complete user authorization, and return to Actagate.
- 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
Section titled “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
Section titled “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
Section titled “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: stringjobs: 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
Section titled “Create an App for a self-hosted deployment”Create a GitHub App in GitHub Developer settings.
- Choose a name and set Homepage URL to the deployment’s public URL.
- Register exactly one Callback URL:
https://<app host>/api/settings/github/callback. Do not use Setup URL. - Enable Request user authorization (OAuth) during installation. Disable Webhook.
- Choose Any account for installation access.
- 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.