To get started using CodeSee Maps, you will need to authorize CodeSee on your GitHub user account, then install and authorize the CodeSee Architecture Diagrams GitHub action on the repositories you’d like to create Maps for.

Installing CodeSee Maps

  1. Go to to sign in.
  2. Select “Connect to GitHub,” then “Authorize Codesee-io” to add CodeSee to your account.
  3. Click “Add a new Map.”
  4. If you are the first person in your GitHub organization to create a Map, you will need to install the GitHub action.
  5. Click “Install” then choose the appropriate organization.
  6. Click “Install & Authorize.”
  7. Select the repository you’d like to create a diagram of and click “Continue.”
  8. Follow the instructions to add the CodeSee API token to your repo’s secrets page, then click “Create Map Diagram.”
  9. Your Map should be ready to explore, annotate, and share!
  10. Updating the CodeSee API Token
  11. Go to your repo’s secrets page.
  12. Click the “Update” button.
  13. Copy the API token, paste it into the form, then click the “Update Secret” button.

Listing Your CodeSee Map in Your Documentation

We've provided a badge for you to use in your documentation (such as a file) below.

View Architecture Diagram badge for CodeSeeView Architecture Diagram badge for CodeSee


We currently request the following GitHub permissions via the CodeSee Maps GitHub App to ensure that you have a smooth experience using CodeSee.

Access to Content and Workflows

We currently run our Maps analysis using a GitHub action (though more options are on the way). Your code is analyzed on GitHub's servers -- we do not store it! Our action sends us aggregate data and metadata about your codebase and then we use that to create your Map, to make insights, and more. In addition, these permissions enable us to open PRs (dependabot style) to install and update the CodeSee Map workflow in your repo to the latest configuration. Finally, if you use our Code Review Maps feature, we display code changes in our UI alongside a Map of the pull request. We do so by requesting only the relevant code using GitHub's APIs, and transmitting it securely over https. Again, we do not store your code.

Access to Pull requests

For pull requests, we generate and post a Review Map on each pull request so that you can see how your change fits within the larger architecture. This image is also a link to the interactive code review interface in the CodeSee app. We need these permissions to post that image.

Access to Actions

These permissions allow us to monitor our GitHub Action, present progress indicators in-app, and help you troubleshoot if something goes wrong.

Access to Repo Administration Organization Members

We use information about who has access to your repo and organization in order to limit who has access to your CodeSee Maps. That way, all those and only those who have access to your repo will have access to your Maps about that repo.

Did this page help you?