Create the GitHub App
Create and connect a private GitHub App for Lifecycle.
Lifecycle creates a private GitHub App from a generated manifest. Before approval, examine the manifest. Install the App only on intended repositories. Continue configuration in Lifecycle.
Before you start
- Lifecycle’s API, UI, identity, DNS, and TLS checks are healthy.
- You can administer the GitHub account or organization that will own the App.
- Your organization has approved the listed permissions and webhook events.
- One or more repositories are ready to grant to the App.
What Lifecycle requests
Lifecycle derives the webhook and setup URLs from its configured public application host:
| Manifest field | Generated destination |
|---|---|
| Webhook | https://app.lifecycle.example.org/api/webhooks/github |
| Setup completion | https://app.lifecycle.example.org/api/v1/setup/installed |
| Setup redirect | https://app.lifecycle.example.org/api/v1/setup/callback |
| Sign-in callback | The GitHub broker callback configured for the identity provider |
app.lifecycle.example.org is a documentation-only hostname. The generated
manifest uses your deployment’s configured host and creates a private
GitHub App.
The generated manifest requests these repository and organization permissions:
| Permission | Level | Why Lifecycle requests it |
|---|---|---|
| Contents | Write | Read Lifecycle configuration and update approved repository files |
| Workflows | Write | Update .github/workflows/* during an approved repository-file change |
| Pull requests | Write | Read and update the pull-request workflow |
| Issues | Write | Create and update issue-style pull-request comments and labels |
| Deployments | Write | Publish deployment-related state |
| Statuses | Read | Read repository commit-status context |
| Metadata | Read | Identify repositories and their metadata |
| Members | Read | Resolve organization membership |
| Emails | Read | Resolve the GitHub user identity |
The App subscribes to:
Workflows: write and the other write permissions are consequential. The generated App requests them for installations that do not use all related features. If your organization cannot approve that boundary, stop. Examine it with the Lifecycle deployment owner. Removing a permission can make enabled workflows not fully functional.
App creation and installation
Open Lifecycle setup
Open https://app.lifecycle.example.org/setup, replacing the documentation
hostname with your Lifecycle API host.
Select Personal or Organization for the account that owns the App.
Name the App
Enter a unique GitHub App name. GitHub App names can contain letters, numbers, and hyphens. Lifecycle accepts at most 34 characters. For an organization-owned App, enter the organization login.
Select Create App. Lifecycle sends the generated manifest to GitHub.
Examine the GitHub manifest
Make sure that the owner, callback URLs, permissions, and events agree with the approved values. Create the App.
Select repository access
Install the App on the repositories that Lifecycle can use. Selecting only approved repositories is narrower than granting all current and future repositories in the account.
Before setup can continue, select one or more repositories.
Continue in Lifecycle
After GitHub returns to Lifecycle, make sure that the installed state is correct. Select Configure and Restart. Before you continue, wait for healthy Lifecycle workloads and UI.
Test the connection
- In GitHub, make sure that the App installation lists the intended repositories.
- In Lifecycle, open
/onboard. - Make sure that an installed repository is available.
- Onboard the repository.
- Open a pull request with a valid
lifecycle.yaml. - Make sure that Lifecycle receives the webhook.
- Make sure that Lifecycle creates the Mission Control comment.
Installing the GitHub App and onboarding a repository are different actions. If GitHub shows the installed App but Lifecycle does not show a repository, examine the App’s repository access before changing Lifecycle configuration.
Continue with repository onboarding.