Documentation nits: I try to add hookshot to a room.

[michaelkaye]

I found a confusion here:

https://matrix-org.github.io/matrix-hookshot/latest/usage/auth.html#github

I think a line inside github informing us how to use the oauth alternative in the DM room as an alternative to the PAT would be useful here.

I found this message is slightly confusing:

Failed to handle command: You must be able to set state in a room ('Change settings') in order to setup new integrations.

I think it would help if it says both you and I need this access, or perhaps "@michaelk:element.io and @hookshot:matrix.org" to be explicit about who needs what.

I found this to be helpful https://matrix-org.github.io/matrix-hookshot/latest/usage/room_configuration/github_repo.html

But I think this could be clearer that both the user running !hookshot and the hookshot bot both need permissions to configure things in the room.

It also says This connection supports a few options which can be defined in the room state:

Which i think is a requirement to head into /devtools and manually edit the room state. Being clearer about the format of this would be good.

It might be good to be explicit that "repo" and "org" are options too; but they should not be updated.

eg:

        "ignoreHooks": ["issue", "pull_request", "release"]

(Also, i'm not clear whether ignoring "issue" is enough to ignore all types under issue, or if we need to ignore the individual types explicitly)

The event type is also still: "type": "uk.half-shot.matrix-hookshot.github.repository",

Which is fine but maybe should be a org.matrix now the repository has changed hands.

[michaelkaye]

(trying to add notes about what i found confusing in the docs / error messages as I use the bot - will try to do some documentation updates as a result of this)

[michaelkaye]

An up-to-date list of !help out of the bot would be useful; I don't want to be "that person" who uses bot commands in a busy room to get help for the bot.

[michaelkaye]

I think we're missing documentation on how to trigger a workflow from a room in the docs.

[michaelkaye]

The generic webhook documentation could use some touchups as well - the content type has to be application/json or it won't be parsed and a confusing error like

<p>Received webhook data:</p><p><pre><code class=\\\"language-json\\\">{}</code></pre></p>

can come from this - it's showing an empty JSON body but what's actually happening is that it's not parsing the JSON in the request body (as it's the wrong content type) so considers the request to be empty, which then shows up as this empty JSON body - but it's unrelated to the contents of the webhook you sent.

I think this is #221

[michaelkaye]

In other news, it's all working fine now, everything was reachable eventually.