GitHub AppCards readme is a little confusing

[testworksau]

Hi Team Miro 👋🏼

I've been looking into spinning up the GitHub AppCards example, and am currently a touch confused as to what I need to do to get this up and running. The instructions say:

add a .env file with the required environment variables (See section at bottom)

and the section has a list of required environment variables, but no indication of what I need to do to obtain them.

I'm not familiar with Vite or Supabase - is there a guide or similar that I can follow to set these things up and obtain the relevant values to populate the env vars with?

[marcospinello]

Hi @testworksau!

Thank you for submitting this issue, and apologies for the lack of clarity about the .env vars. We logged a ticket to expand this section of the Readme to add the missing information and include examples.

In the meantime, can this commented code block get you unblocked? If not, what else can we do to get you up and running asap?

For more information on Vite .env files: see https://vitejs.dev/guide/env-and-mode.html#env-files

# Generate an access token in GitHub, and enter the value here.
# To generate the access token go to https://github.com/settings/tokens
VITE_GH_ACCESS_TOKEN=

# Enter here the password for the database you created on in Supabase.
VITE_SUPABASE_PASSWORD=

# Enter here the URL of the Supabase database that the app uses for data persistence.
# For more information, see https://supabase.com/docs/guides/database
VITE_DATABASE_URL=

# Enter here the API key of the Supabase project with the database that the app uses for data persistence.
# For more information, see https://supabase.com/docs/guides/api#api-url-and-keys
VITE_DATABASE_PUBLIC_KEY=

# Enter here the base URL of the hosting servece your app is running on.
# If you're developing locally, it can be 'localhost' for example.
VITE_BASE_URL=

# Ignore this field, it's no longer necessary. We'll update the README accordingly.
VITE_MIRO_API_TOKEN=

# Enter here the client secret of your app.
# For more information, see
# https://developers.miro.com/docs/build-your-first-hello-world-app#step-4-configure-your-app-in-miro
MIRO_CLIENT_SECRET=

# Enter here the OAuth code grant flow redirect URI for your app.
# For more information, see:
# https://developers.miro.com/docs/getting-started-with-oauth
# https://developers.miro.com/reference/authorization-flow-for-expiring-access-tokens
MIRO_REDIRECT_URI=

[testworksau]

That's super helpful, thanks @marcospinello 🎉

Some things I think would be useful would be:

1. Documenting the scope of the GH token; I assume it only requires the repo read / write access level?
2. Documenting the required / minimum Miro App permissions / scopes for this example
3. Elaborating on the MIRO_REDIRECT_URI with an example. i.e. is that just:

https://miro.com/oauth/authorize?response_type=code
&client_id=<the client id generated when you create a new Miro app>
&redirect_uri=<the url of the app that matches the "App URL" set during creation of a new app e.g. the same as VITE_BASE_URL>

or is it something else?

If it's what I've guessed above, is there a reason the example wouldn't just require a MIRO_CLIENT_ID and self-build the MIRO_REDIRECT_URI from that and the VITE_BASE_URL fields?

[marcospinello]

hi @testworksau ,

Thank you for you reply and the extra feedback -- I'll add the missing points you mention to the docs 👍

• GitHub token: indeed just repo read/write access.

• Minimum board permissions: as a rule of thumb, if your app just gets data about board items and the board, boards:read.
  If your app also modifies data, for example by changing board items content or dimensions, the app requires also boards:write.

• About MIRO_REDIRECT_URI: it corresponds to the OAuth redirect_uri URL parameter in the URL you use to get the temp code and then exchange it for an access token.

  &redirect_uri=<the url of the app that matches the "App URL" set during creation of a new app e.g. the same as VITE_BASE_URL>

  The redirect_uri is the URL to which you want the user to be redirected after the authorization is complete. This must match the redirect URL that you have previously registered with the service.

  This video has more details about getting started with OAuth and Miro.