GitHub
You can connect Stretchy to GitHub, GitHub Enterprise Cloud, and GitHub Enterprise Server and run GitHub Actions workflows on the machines of your choice.
| While Stretchy’s provisioners support more hardware platforms and operating systems than GitHub Actions, you are limited to the platforms supported by GitHub Actions Runner. Furthermore, many actions have not been tested on any other Linux distribution than Ubuntu. |
Connecting Stretchy to GitHub is a four-step process:
-
Register a GitHub App.
-
Create a GitHub connection in Stretchy.
-
Install the GitHub App into the personal GitHub account or GitHub organization you want to connect to Stretchy.
-
Configure your GitHub Actions workflows to send jobs to Stretchy by attaching the right labels to each job with
jobs.<job_id>.runs-on.
GitHub’s organizations and projects map directly to Stretchy’s organizations and projects.
Registering a GitHub App
Values to enter:
- GitHub App name
-
Pick any suitable name, for example, "MyCompany Stretchy".
- Homepage URL
-
Enter the public URL of your Stretchy instance.
- Webhook URL
-
Enter the public URL of your Stretchy instance. You have to change that value once you have created the GitHub Connection in Stretchy.
- Secret
-
Enter a strong, randomly generated password.
- Repository permissions
-
Select Read and write for Actions and Administration[1].
- Subscribe to events
-
Select Installation target, and Workflow job.
- Where can this GitHub App be installed?
-
On GitHub, select Only on this account. On GitHub Enterprise Cloud and GitHub Enterprise Server, choose the option that fits your needs.
After registering the GitHub App, write down its App ID. Further, generate and download a Private Key to sign access token requests. You need those to create a GitHub connection in Stretchy Orchestrator.
Creating a GitHub Connection in Stretchy
In Stretchy Orchestrator, go to Connections, click on Add connection, and select GitHub. Follow the instructions displayed by the web interface.
After creating the connection, click on Set up next to the newly created connection. Copy the Webhook URL. Then, on GitHub, go back to the GitHub App you created and enter it into the field Webhook URL.
| When Stretchy Orchestrator does not receive webhook notifications from GitHub, check whether the Webhook URL of the GitHub App matches the one displayed by Stretchy’s Set up page. |
| Before renaming or transferring a GitHub repository, remove the GitHub app from it and reinstall it again after the repository has been renamed or transferred. |
Installing the GitHub App
Follow GitHub’s documentation on Installing your own GitHub App.
Once a GitHub App is installed into a repository, a matching project should automatically appear in Stretchy Orchestrator. Likewise, it should automatically be removed once the GitHub App is removed from a repository.
Configuring GitHub Actions Workflows
Stretchy Orchestrator provides an assistant to create a label combination that you can copy into your GitHub Actions workflow:
-
Go to Projects and click on Set up next to the project whose GitHub Actions jobs should be routed to Stretchy.
-
Select one flavour and one image.
-
Copy the generated label combination into the
jobs.<job_id>.runs-onstanza of your GitHub Actions workflow.
The label assistant will automatically add any required labels.
The label assistant inserts ${{ github.run_id }}-${{github.run_attempt}} into every label combination. That expression is necessary to ensure that a job ends up on the machine that was created for it.
|
Switching Between Hosted Runners and Stretchy
You can decide on a per-job basis whether a job should be run by one of GitHub’s hosted runners or Stretchy by setting appropriate labels in a job’s runs-on configuration:
-
Stretchy ignores jobs it cannot run. A job without labels that match at least one flavour and one image are rejected.
-
Stretchy ignores jobs without labels whose presence is required by the corresponding GitHub connection.
Similarly, GitHub’s hosted runners ignore jobs whose entire combination of labels does not match the labels of a hosted runner. For more information, see the GitHub documentation on jobs.<job_id>.runs-on.
Considerations
Event Notifications Can Get Lost
Stretchy Orchestrator relies on GitHub sending event notifications, for example, that a job has been queued. However, GitHub does not guarantee the delivery of those events. If an event gets lost, Stretchy might not start a machine for a job because it does not know about it. In such a case, the best course of action is to cancel the job on GitHub’s side and tell GitHub to retry it.