Skip to content
This documentation is a preview of the pull request #2253

For the latest updates and improvements in production, open docs.codacy.com instead.

Adding repositories to Codacy programmatically#

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 many repositories to Codacy, such as when initially adding all repositories in your Git provider organization

To add repositories programmatically, use the Codacy 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: Account API token used to authenticate on the Codacy API.

  • GIT_PROVIDER: Git provider hosting of 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're using GitLab you must specify the full group path and the repository using the format <group>/<subgroup-1>/.../<subgroup-N>/<repository>.

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, add repositories in small batches or space out adding new repositories over time.

The example script:

  1. Defines a GitHub personal access token, the GitHub organization name, and the account API token used to authenticate on the Codacy API.
  2. Calls the GitHub API to obtain the list of all repositories in the defined organization.
  3. 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>.
  4. For each repository, calls the endpoint addRepository to add a new repository specifying gh as the Git provider and the value of full_name as the full path of the repository.
  5. Checks the HTTP status code obtained in the response and performs basic error handling.
  6. Pauses a few seconds between requests to the Codacy API to avoid rate limiting.
#!/bin/bash

GITHUB_AUTH_TOKEN="<your GitHub personal access token>"
GITHUB_ORG_NAME="<your GitHub organization name>"
CODACY_API_TOKEN="<your account API token>"

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 60 # Pause between repositories
done

Important

For the sake of simplicity, the example doesn't consider paginated results obtained from the Codacy API. Learn how to use pagination to ensure that you process all results returned by the API.

Besides this, the script doesn't consider paginated results obtained from the GitHub API. Learn how to use pagination on the GitHub API to ensure that you obtain all the repositories in your organization.

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?

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

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

Thanks for helping improve the Codacy documentation.

Edit this page on GitHub if you notice something wrong or missing.

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

Last modified January 25, 2023