Connect GitHub

This connection sends each article to the GitHub repository your site is built from, as a pull request. Nothing goes live until your team merges it, and your repository's own checks run on it like on any other pull request.

What you need

• A site built with Hugo from a GitHub repository, with its posts in content/blog, content/posts or content/post, or in a folder you name.
• Permission to create a token for that repository. For an organization's repository, you need to be a member of the organization with write access to the repository. If the organization approves tokens, an owner approves yours.

In GitHub

1. Open Settings, then Developer settings, Personal access tokens and Fine-grained tokens, and click Generate new token.
2. Under Resource owner, choose the organization that owns the repository, or yourself.
3. Choose an Expiration. When the token expires, create a new one and paste it in the same place.
4. Under Repository access, choose Only select repositories and pick the repository.
5. Under Permissions, give the token Contents and Pull requests, each set to Read and write.
6. Click Generate token and copy it.

In Gofylo

1. Open Integrations and click Connect on the GitHub card.
2. Fill in Repository (owner/name, or its address on GitHub) and Access token. Branch (optional), Folder for posts (optional) and Extra front matter (optional) can stay empty.
3. Click Check connection. It reads the repository without changing anything, then says where posts will go, or what to fix.
4. Click Connect.

Extra front matter is added to every post, for a key your site needs that Gofylo doesn't fill, such as topic: "events". For several keys, write them as {topic: "events", layout: "post"}.

To change the details later, click Configure on the card, change what you need and click Update credentials. Leave the access token empty to keep the one already saved: its box reads Saved. Leave blank to keep it.

What gets published

An article goes out when you click Approve & Publish on it, or on its scheduled day when Auto-publish articles is on in Content Settings. Each article becomes one pull request on your repository: the post in your folder for posts, with its cover image beside it, and front matter with its title, date, author, description and the tags your site already uses. The article reads In review until your team merges the pull request, then Published. The top of the editor links to the pull request.

• Republish while the pull request is open adds your changes to the same pull request. After it is merged, Republish opens a new pull request with the changes.
• An edit made in GitHub itself is replaced the next time the article is sent. Make your changes in Gofylo.
• A pull request closed without merging reads Not merged, and is never sent again on its own. Approve & Publish sends a new one.
• Deleting the article in Gofylo closes its open pull request. For a post already on your site, it opens a pull request that removes the post.

What Check connection tells you

• "GitHub refused the token": copy the token again in full, or create a new one.
• "GitHub found no repository": check the name, and that the token was made for this repository.
• "GitHub refused the token for this repository": edit the token on GitHub so it can use this repository, with Contents and Pull requests set to Read and write.
• "The token can open the repository but not its pull requests": set Pull requests to Read and write on the token.
• "We couldn't find where your posts live": fill in Folder for posts (optional).
• "This repository is archived": unarchive it on GitHub first.

Check connection only reads, so your first post's pull request is the test that the token can write.

If it doesn't work

Open the article and expand Advanced > Publish history to see what happened. A send that went in for review links to its pull request.

• "Your site refused the connection details": the token was refused or is missing a permission. Create a new one, paste it into Access token and click Update credentials.
• "Your site didn't accept the article": click Check connection on the GitHub card to see what to fix.
• "Your site didn't answer after several tries": GitHub didn't answer. Click Approve & Publish on the article again later.