How do I programmatically add repositories to Codacy?¶

There are scenarios where manually adding Git repositories on the Codacy UI is inconvenient or time-consuming. For example:

You want to add all new repositories to Codacy when they're created on the Git provider
You're adding a large number of repositories to Codacy, such as when initially adding all repositories in your Git provider organization

To add repositories programmatically, use Codacy's API v3 endpoint addRepository by performing an HTTP POST request to /repositories, specifying the Git provider and the full path of the repository in the body of the request:

curl -X POST https://app.codacy.com/api/v3/repositories \
  -H 'Content-Type: application/json' \
  -H 'api-token: <API_KEY>' \
  -d '{"provider":"<GIT_PROVIDER>", "repositoryFullPath":"<REPOSITORY_FULL_PATH>"}

Substitute the placeholders with your own values:

API_KEY: API token used to authenticate on the Codacy API.
GIT_PROVIDER: Git provider hosting the repository, using one of the values in the table below. For example, gh for GitHub Cloud.

Value Git provider

gh GitHub Cloud

ghe GitHub Enterprise

gl GitLab Cloud

gle GitLab Enterprise

bb Bitbucket Cloud

bbe Bitbucket Server
REPOSITORY_FULL_PATH: Name of the organization and repository on the Git provider, using the format <organization>/<repository>. For example, codacy/docs. You must have admin permissions over the repository on the Git provider.

Important

If you are using GitLab you must specify the full group path and the repository using the format <group>/<subgroup-1>/.../<subgroup-N>/<repository>.

Currently, Codacy doesn't provide API endpoints to automate other parts of setting up new repositories, such as configuring the repository settings or the enabled code patterns. However, Codacy automatically applies the default patterns defined on the Codacy API token account to the new repositories, and you can use this to ensure that all new repositories share the same pattern configuration.

Example: Adding all repositories in a GitHub organization¶

We provide an example Bash script that adds all repositories in a GitHub Cloud organization to Codacy. We suggest that you adapt the script to your specific scenario.

Warning

Since Codacy automatically analyzes new repositories, adding many repositories in a short time can cause delays in the analysis of other repositories depending on the size of the repositories, the sizing of the infrastructure, and the concurrent analysis configuration. For example:

Repositories added	Expected delay
1 to 10	Small
11 to 100	Considerable
More than 100	Extreme

To avoid these delays, we recommend that you add repositories in small batches or that you space out adding new repositories in time.

The example script:

Defines a GitHub personal access token, the GitHub organization name, and a Codacy API token.
Calls the GitHub API to obtain the list of all repositories in the defined organization.
Uses jq to return the value of full_name for each repository obtained in the JSON response. The full_name already includes the organization and repository names using the format <organization>/<repository>.
For each repository, calls the Codacy API endpoint to add a new repository specifying gh as the Git provider and the value of full_name as the full path of the repository.
Checks the HTTP status code obtained in the response and performs basic error handling.
Pauses a few seconds between requests to the Codacy API to avoid rate limiting.

#!/bin/bash

GITHUB_AUTH_TOKEN="<REPLACE_ME>"
GITHUB_ORG_NAME="<REPLACE_ME>"
CODACY_API_TOKEN="<REPLACE_ME>"

printf "Obtaining all repositories in the $GITHUB_ORG_NAME organization\n"
for repo in $(curl -s https://api.github.com/orgs/$GITHUB_ORG_NAME/repos -H "Authorization: Bearer $GITHUB_AUTH_TOKEN" | jq -r '.[] | .full_name'); do
  printf "Adding $repo to Codacy\n"
  http_status=$(curl -X POST https://app.codacy.com/api/v3/repositories \
                     -H "Content-Type: application/json" \
                     -H "api-token: $CODACY_API_TOKEN" \
                     -d '{"provider":"gh", "repositoryFullPath":"'$repo'"}' \
                     -sSo /dev/null -w "%{http_code}")
  case "$http_status" in
    200) printf "$repo added successfully\n"
         ;;
    401) printf "Error: 401 Unauthorized, check the Codacy API token\n"
         break
         ;;
    409) printf "Error: 409 Conflict, $repo is already added to Codacy\n"
         ;;
      *) printf "Error: $http_status HTTP status code\n"
         break
         ;;
  esac
  sleep 10 # Wait 10 seconds
done

Important

For the sake of simplicity:

The GitHub API endpoint used by the script obtains all repositories in a GitHub organization. However, you must have admin permissions over the repositories that you add to Codacy. If you are not the owner of all the repositories in your GitHub organization, consider using the GitHub API endpoint /user/repos instead.
The script doesn't take into account paginated results obtained from the GitHub API. To ensure that you obtain all the repositories in your organization, learn how to use pagination on the GitHub API.

Share your feedback 📢

Did this page help you?

Thanks for the feedback! Is there anything else you'd like to tell us about this page?

255 characters left

We're sorry to hear that. Please let us know what we can improve:

255 characters left

Alternatively, you can create a more detailed issue on our GitHub repository.

Thanks for helping improve the Codacy documentation.

If you have a question or need help please contact support@codacy.com.

Last modified November 26, 2020

Value	Git provider
`gh`	GitHub Cloud
`ghe`	GitHub Enterprise
`gl`	GitLab Cloud
`gle`	GitLab Enterprise
`bb`	Bitbucket Cloud
`bbe`	Bitbucket Server