This documentation is a preview of the pull request #2253

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

Creating repository API tokens programmatically#

To create new repository API tokens for your Codacy repositories programmatically, use the Codacy API endpoint createRepositoryApiToken. You can also list all repository API tokens for a repository using the endpoint listRepositoryApiTokens.

For example, if you're setting up coverage for all your repositories and prefer not to use a single account API token that grants the same permissions as an administrator, you need to create an individual repository API token for each repository.

Example: Creating a repository API token for a single repository#

This example creates a new repository API token for a repository and outputs the new token string.

The example script:

Defines the account API token used to authenticate on the Codacy API, the Git provider, the organization name, and the repository name passed as an argument to the script.
Calls the endpoint createRepositoryApiToken to create a new repository API token and uses jq to obtain only the created token string.

#!/bin/bash

CODACY_API_TOKEN="<your account API token>"
GIT_PROVIDER="<your Git provider>" # gh, ghe, gl, gle, bb, or bbe
ORGANIZATION="<your organization name>"
REPOSITORY=$1

curl -sX POST "https://app.codacy.com/api/v3/organizations/$GIT_PROVIDER/$ORGANIZATION/repositories/$REPOSITORY/tokens" \
     -H "api-token: $CODACY_API_TOKEN" \
| jq -r ".data | .token"

Example usage and output

$ ./create-token.sh website
<new repository API token>

Example: Creating repository API tokens for all repositories in an organization#

This example creates new repository API tokens for all the repositories in an organization and outputs a comma-separated list of repository names and corresponding token strings.

The example script:

Defines the account API token used to authenticate on the Codacy API, the Git provider, and the organization name.
Calls the endpoint listOrganizationRepositories to retrieve the list of repositories in the organization.
Uses jq to select only the name of the repositories.
Asks for confirmation from the user before making any changes.
For each repository, calls the endpoint createRepositoryApiToken to create a new repository API token and uses jq to obtain only the created token string.
Outputs a comma-separated list of the repository names and the corresponding new token strings.
Pauses a few seconds between requests to the Codacy API to avoid rate limiting.

#!/bin/bash

CODACY_API_TOKEN="<your account API token>"
GIT_PROVIDER="<your Git provider>" # gh, ghe, gl, gle, bb, or bbe
ORGANIZATION="<your organization name>"

repositories=$(curl -sX GET "https://app.codacy.com/api/v3/organizations/$GIT_PROVIDER/$ORGANIZATION/repositories" \
                    -H "api-token: $CODACY_API_TOKEN" \
               | jq -r ".data[] | .name")

count=$(echo "$repositories" | wc -l)
read -p "Create repository tokens for $count repositories? (y/n) " choice
if [ "$choice" = "y" ]; then
    echo "$repositories" | while read repository; do
        echo -n "$repository,"
        curl -sX POST "https://app.codacy.com/api/v3/organizations/$GIT_PROVIDER/$ORGANIZATION/repositories/$repository/tokens" \
             -H "api-token: $CODACY_API_TOKEN" \
        | jq -r ".data | .token"
        sleep 2 # Wait 2 seconds
    done
else
    echo "No changes made.";
fi

Example output:

chart,<new repository API token>
docs,<new repository API token>
website,<new repository API token>
[...]

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.

Example: Listing the repository API tokens for a repository#

This example lists all repository API tokens created for a repository.

The example script:

Defines the account API token used to authenticate on the Codacy API, the Git provider, the organization name, and the repository name passed as an argument to the script.
Calls the endpoint listRepositoryApiTokens to list the repository API tokens available on the repository and uses jq to obtain only the token strings, or exit with a non-zero status if the repository doesn't have any repository API tokens created yet.

#!/bin/bash
CODACY_API_TOKEN="<your account API token>"
GIT_PROVIDER="<your Git provider>" # gh, ghe, gl, gle, bb, or bbe
ORGANIZATION="<your organization name>"
REPOSITORY=$1

curl -sX GET "https://app.codacy.com/api/v3/organizations/$GIT_PROVIDER/$ORGANIZATION/repositories/$REPOSITORY/tokens" \
     -H "api-token: $CODACY_API_TOKEN" \
| jq -er ".data[] | .token"

Example usage to obtain only the repository API token created most recently for the repository:

$ ./list-tokens.sh website | head -n 1
<last repository API token created>

Creating repository API tokens programmatically#

Example: Creating a repository API token for a single repository#

Example: Creating repository API tokens for all repositories in an organization#

Example: Listing the repository API tokens for a repository#

See also#

Share your feedback 📢