GitHub App deployments

This guide shows how to deploy a repository with a GitHub App. GitHub sends push and pull request events to the control node. The control node deploys the services in up.yaml.

No GitHub Actions runner is used. A deploy does not use Actions minutes while a build runs.

Before you start

You need:

  • a control node that GitHub can reach over HTTPS;
  • a node with the deploy role;
  • an up.yaml file at the root of the repository;
  • permission to create a GitHub App on your account or organization.

1. Set the public URL

The plugin must know the public URL of the control node. Open ~/.config/up/config.toml on the control node. Add this table:

[plugins.github]
public_url = "https://up.example.com"

Replace the URL with the URL of your control node. Use https://. Use http://localhost:7070 only for a local test. Save the file.

2. Create the App

Run:

up plugin github init

The command prints a URL and opens your browser.

  1. On the GitHub page, click Create GitHub App. GitHub creates the App from a prefilled template. The template sets the permissions and the events that up needs.
  2. Wait in the terminal. The command writes the App settings to the control node config. It writes the private key to ~/.config/up/plugins/github/app.pem with mode 0600. It reloads the plugin. You do not restart the control node.
  3. Continue when the command reports that the App is configured. The command checks the control node, so it finishes by itself.

The App is public. Any account or organization can install it. GitHub cannot change a public App back to private.

3. Install the App

Run:

up plugin github install

The command opens the install page. Select the account or organization. Select the repositories. Click Install.

To see where the App is installed, run:

up plugin github installations

4. Turn off the old workflows

If the repository uses the up deploy action, turn it off. Delete or disable .github/workflows/deploy.yml and .github/workflows/preview.yml. The App now sends the events that the workflows sent before.

5. Check the result

Push a commit to the default branch. Up deploys the production environment. Open the repository on GitHub. GitHub shows a check run for the commit, and a deployment with the URL of the first service.

For a pull request, up deploys the environment pr-<number> and writes one comment on the pull request. When the pull request closes, up removes the environment.

What up does with each event

  • A push to the default branch deploys production.
  • A push to another branch deploys an environment with the name of the branch.
  • A pull request deploys pr-<number> as a preview.
  • A closed pull request removes the preview environment.

The preview block in up.yaml sets the preview domain. See Preview environments.

Approvals

A deploy starts as soon as GitHub sends the event. A GitHub environment approval rule does not apply, because no workflow job runs. To approve production changes, protect the default branch. Then a change reaches production only through a reviewed pull request.

Limits

  • The installation token is valid for one hour. A build that runs longer than one hour cannot push the image. Use a registry credential that lasts longer for very long builds.
  • GitHub can send the same event more than once. Up ignores a repeat event, so a retry does not start a second deploy.
  • Up runs one deploy at a time for the same repository and environment. A second push waits for the first to finish.
  • A pull request from a fork does not deploy. The App cannot read the fork.
  • Up handles only push and pull_request events. It ignores other events.

Set the values by hand

You can skip the browser and set the values yourself. Open ~/.config/up/config.toml and add:

[plugins.github]
app_id = 123456
private_key_path = "/etc/up/github-app.pem"
webhook_secret = "the-webhook-secret"
public_url = "https://up.example.com"

Restart the control node after you change the file.

For GitHub Enterprise Server, also set api_base_url to the API root, for example https://ghe.example.com/api/v3. Do not set it on github.com.

The values stay on the control node. The node config API cannot change them, so the private key and the webhook secret do not leave the machine.

To read more about plugins, see Plugins.