Skip to content
This documentation applies to Codacy Self-hosted v4.0.1

For the latest updates and improvements, see the latest Cloud documentation 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 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: Account 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're 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:

  1. Defines a GitHub personal access token, the GitHub organization name, and an account API token.
  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 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.
  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="<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're 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?

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.

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

Last modified April 13, 2021