GitHub Connection¶
Using GitHub¶
There are lots of advantages to hosting custom templatests on GitHub. In addition to the features like collaboration and version control that you get with GitHub and similar services, ActionKit's GitHub integration makes it easier to work on custom templatesets.
When you commit and push changes to your public or private GitHub repositories, they're automatically applied to your connected templatesets in ActionKit. That applies to previews too. Once you configure a preview branch in ActionKit, push to the branch and open a page preview so you (and not your members) can see your changes, making for faster development and fewer surprises.
Also, starting in early 2022, ActionKit's built-in Original templateset is published to GitHub. Consider forking the TheWalkers/ActionKit-Original repository for your new projects and integration of new ActionKit features and fixes into your customized templates can be a few clicks away.
Connecting Your Templateset To A GitHub Repository¶
The "Change Templateset" screen allows you to connect a GitHub repository to your Templateset. Keep your Templatesets in GitHub, but automatically send the changes to ActionKit when you push. Changes made in ActionKit will never be sent to GitHub, it's a one-way connection.
To connect a repository, you'll need to synchronise your files, add a GitHub repository and settings to ActionKit, and install the webhook and deploy key.
Synchronise Your Files¶
It is important that your GitHub repository and ActionKit contain the same versions of the Templateset files when you initialize the connection. ActionKit won't synchronise them for you.
If you don't have your templateset in a repository yet:
- Download the ActionKit Templateset
- Add the Templateset to the repository
- Configure the connection
If you do have your templateset in a repository, you need to make sure ActionKit and the repository have the same files. Here's one way to do that:
- Download the ActionKit Templateset
- Commit any changes to Git and push to GitHub
- Upload the merged version to ActionKit
- Configure the connection
You can find the download link on the Template Picker page.
Add A Github Repository And Settings¶
Now that you are sure you have the same versions in both places, you can configure the connection to GitHub. Here is a description of the fields you need to provide:
Setting Description Repository Select from the list of GitHub repositories ActionKit knows about. Use the to add a new Repository.
Path The path in the repository to this Templateset. If your Templateset is the only directory in the repository, leave this empty. Live branch Changes to this branch will be saved to the Templateset when they are pushed to GitHub. Defaults to "master". Preview Branch Changes to this branch will be saved as previews when they are pushed to GitHub. Defaults to "preview".
To add a new Repository, use the . You'll need to fill in the following fields:
Setting Description Owner The username at GitHub that owns the repository. Repository The name of the repository at GitHub. Private Is this a private repository? We need to know.
The "Owner" and "Repository" are easy to find from the URL of your repository at GitHub. If your Templateset is in a repository accessible at:
https://github.com/aaronelliotross/actionkit-templatesets/
"aaronelliotross" is the owner. "actionkit-templatesets" is the repository.
All changes pushed to GitHub on a repository will be sent to ActionKit. We'll use these settings to figure out which commits should be applied to this Templateset. The owner and repository fields will be matched against the repository, the branch will be matched against the branches configured here, and the filepath of the modified file will be checked against Path.
Here's a quick example. In your GitHub account "yourloginname", you have a repository "actionkit" and in that repository, you have a directory named "templatesets", where each templateset has it's own directory:
github.com/yourloginname/
|
--> actionkit/
|
--> templatesets/
|
--> Blue/
--> wrapper.html, ...
|
--> Red/
--> wrapper.html, ...
To connect the Red templateset, you'd enter a Path of "templatesets/Red", and configure the repository with the owner "yourloginname", and the repository "actionkit".
Once you've got your Repository, Path and Branches configured, you'll need select an option to install the webhook and deploy key.
Install The Webhook And Deploy Key¶
You can either let us automatically install the webhook and deploy key, or if you are not comfortable granting access to the ActionKit Templateset Integration application, install them yourself manually.
Automatically configuring the connection requires granting ActionKit read / write access to your repositories, see below for more details.
Save Manually¶
To manually install the settings on GitHub, save your changes with the 'Save and install at GitHub Manually' button.
The resulting page has instructions, as well as settings specific to each Templateset you'll need to get the connection working.
The basic steps, on GitHub, are:
- Find the settings for the repository you want to connect.
- Add a webhook, using the URL and secret key we provide on the manual install page.
- Add a read-only deploy key, using the public key we provide on the manual install page.
Save With oAuth¶
To use oAuth to install the webhook and deploy key, Actionkit will need you to grant it permission via oAuth.
Once you've granted permission, we'll automatically install both the webhook and the deploy key. You'll see ActionKit Templateset Integration as the name of the oAuth application. You can verify the settings we've added in the repository settings menu.
Use the 'Save and install at GitHub with oAuth' button to have us install the settings automatically.
GitHub's API requires that we ask for two scopes (oAuth permissions):
- write:repo_hook, access to read / write webhooks on repositories you have access to.
- repo / public_repo, read / write access to repositories you have access to.
If the repository you want to connect is private, we'll ask for access to your private repositories. If it's public, we can limit our request to public repositories.
NOTE: We don't need full access to your repositories, but GitHub doesn't provide a scope for installing deploy keys, nor a way to revoke scopes that we can access via the API. We do not store the oAuth token once we've used it - we revoke it after we're done - but the application must remain authorized or the deploy keys will be deleted.
Let us know if you have trouble with getting the connection setup! There are a lot of possible configurations and we probably haven't seen them all yet.
Once we've got your permission, we'll install the Webhook and send you back to the Templateset template editor.
Debugging Problems With The Connection¶
- Check that the WebHook is getting a 200 response in GitHub. You can click on the WebHook URL to see recent requests and responses. If they are not succeeding, check the URL, copy the signature again, and re-send a request.
- Check that the deploy key is installed on the right repository. You can copy the public key from the installing manually page, if it's missing.
- Check that the Paths match.
- Check that the branches exist in the repository and match.
- Still stuck? Submit a support ticket.
Using The Connection To Change Preview Templates¶
Changes you push to the preview branch will create preview templates, visible on the Template Picker page under "Unsaved Changes".
You must use the Preview button to enter preview-mode.
However, once you are looking at a Page with the previews, if you push additional changes, simply reloading will load the new version of the preview. There is, of course, a delay between your push to GitHub and the time ActionKit gets notified.
Read more about previewing changes.
Using The Connection To Push Changes Live¶
If you push changes to the master branch, they will immediately be applied to your Templateset and to all pages using that Templateset. There is no undo button, though you can always use Git to push a reversion of your changes.