Repositories¶
Repositories store code, models, datasets, and other content. With the API you can create, update, transfer, and archive repositories, read and write files, fork repositories and synchronize them with the source, configure repository settings and member permissions, and inspect contributors, activity, and download statistics.
Branches, tags, commits, releases, and webhooks have their own groups and are not repeated here.
Objects¶
| Object | Description | Related endpoint |
|---|---|---|
| Repository | Basic information such as name, description, path, visibility, and default branch | Update repository settings |
| File | Files and directories in the repository; can be read, created, updated, and deleted | Get contents at a specific repository path |
| Blob | File content object, read by SHA | Get file blob |
| Directory tree | Retrieve the directory structure recursively by branch, commit, or tree SHA | Get repository directory tree |
| Fork | A derived copy of a repository that can be synchronized with the source | Fork a repository |
| Settings | Repository settings, pull request settings, push rules, permission mode, project modules | Get repository settings |
| Members and roles | Member permission levels and custom roles | Update project member roles |
| CLA | Viewing and configuring the Contributor License Agreement | Get the CLA list of a repository |
| Star / Watch | Users who star or watch the repository | List users who have starred the repository |
| Statistics | Language distribution, contributors, contributor statistics, download counts | Get repository languages |
| Remote mirror | Pushed remote mirrors and remote mirror configuration | Query the list of remote mirrors pushed by the repository |
| License agreement | The repository's LICENSE file and SPDX information | Get the repository license agreement |
Identification¶
- Repositories are identified by the path parameters
ownerandrepo:owneris the namespace address to which the repository belongs (the path of the enterprise, organization, or user), andrepois the repository path. - Files are identified by the path parameter
path, which is the file's path inside the repository. - Updating or deleting a file requires the file's current blob SHA, which you can obtain with Get contents at a specific repository path.
- A few endpoints, such as archiving and transfer, use
org+repoororg+projectsand their paths do not start with/repos/.
Common tasks¶
| Task | Endpoint |
|---|---|
| Create a repository in an organization | POST /api/v5/orgs/{org}/repos |
| Update basic repository information | PATCH /api/v5/repos/{owner}/{repo} |
| Read a file or directory | GET /api/v5/repos/{owner}/{repo}/contents/{path} |
| Create a file | POST /api/v5/repos/{owner}/{repo}/contents/{path} |
| Update a file | PUT /api/v5/repos/{owner}/{repo}/contents/{path} |
| Delete a file | DELETE /api/v5/repos/{owner}/{repo}/contents/{path} |
| Get a raw file | GET /api/v5/repos/{owner}/{repo}/raw/{path} |
| Fork a repository | POST /api/v5/repos/{owner}/{repo}/forks |
| Synchronize a forked repository | PUT /api/v5/repos/{owner}/{repo}/sync_repo |
| Update a member role | PUT /api/v5/repos/{owner}/{repo}/members/{username} |
| Transfer a repository | POST /api/v5/repos/{owner}/{repo}/transfer |
| Archive a repository | PUT /api/v5/org/{org}/repo/{repo}/status |
Notes¶
- A set of archive and transfer endpoints starts with
/org/, unlike the other/repos/{owner}/{repo}/…endpoints: archiving isPUT /api/v5/org/{org}/repo/{repo}/status, transfer also hasPOST /api/v5/org/{org}/projects/{repo}/transfer, andPOST /api/v5/repos/{owner}/{repo}/transferis a different transfer entry point. Confirm the target namespace type before calling. - There are two different "update repository settings" endpoints, distinguished by purpose:
PATCH /api/v5/repos/{owner}/{repo}changes basic information such as name, description, default branch, and visibility;PUT /api/v5/repos/{owner}/{repo}/repo_settingschanges repository settings. - When creating or updating a file,
contentmust be Base64-encoded; updating and deleting also require the original file's blob SHA, otherwise you get a conflict. - Uploading attachments (
POST /api/v5/repos/*/*/file/upload) is limited to 20M, and the path uses*placeholders instead of{owner}/{repo}. - Uploading images and uploading attachments are two different endpoints; their return values are used for inline images and attachment downloads respectively, so do not mix them up.
Endpoint list¶
This module contains 44 endpoints in total.
| # | Endpoint | Method and path | Description |
|---|---|---|---|
| 1 | Create a repository | POST /api/v5/orgs/{org}/repos |
Creates a new repository in the specified organization. Supports code, model, dataset, and other repository types, public or private visibility, and configuration of the default branch,… |
| 2 | Get repository directory tree | GET /api/v5/repos/{owner}/{repo}/git/trees/{sha} |
Retrieves the directory tree of the specified repository. The version can be located by branch name, commit, or directory tree SHA; subdirectories can be fetched recursively and the result viewed page by page… |
| 3 | Get contents at a specific repository path | GET /api/v5/repos/{owner}/{repo}/contents/{path} |
Retrieves the file content or directory entries at the specified repository path, returning the file type, size, content encoding, and SHA value, along with the corresponding API… |
| 4 | Create a file | POST /api/v5/repos/{owner}/{repo}/contents/{path} |
Creates a file in the specified repository. The request must include the Base64-encoded file content and a commit message, and you can optionally specify the commit branch and committer information… |
| 5 | Update a file | PUT /api/v5/repos/{owner}/{repo}/contents/{path} |
Updates the content of the file at the specified path in the specified repository. Requires the Base64-encoded new content, the original file's blob SHA, and a commit… |
| 6 | Delete a file | DELETE /api/v5/repos/{owner}/{repo}/contents/{path} |
Deletes a file on the specified branch of the repository. The target file is identified by its path and blob SHA; the deletion automatically creates a corresponding… |
| 7 | Get the file list | GET /api/v5/repos/{owner}/{repo}/file_list |
Retrieves the file list of the specified repository. The file version can be located by branch, tag, or commit information, and files can be found by name; the response returns all files in the repository… |
| 8 | Get a file blob | GET /api/v5/repos/{owner}/{repo}/git/blobs/{sha} |
Retrieves the file blob content for the specified repository and file blob SHA, returning the content size, resource access URL,… |
| 9 | Get repository languages | GET /api/v5/repos/{owner}/{repo}/languages |
Retrieves the language distribution of the specified repository, returning a map from language name to the percentage of the repository's code it accounts for, which helps users understand the… |
| 10 | Get repository contributors | GET /api/v5/repos/{owner}/{repo}/contributors |
Queries the contributors of the specified repository, returning contributor names, contribution counts, and emails. Supports counting by committers or authors… |
| 11 | Set project modules | PUT /api/v5/repos/{owner}/{repo}/module/setting |
Sets the project modules of the specified repository. You can enable or disable wiki, issues, security configuration, merge requests, and… |
| 12 | Update repository settings | PATCH /api/v5/repos/{owner}/{repo} |
Updates the settings of the specified repository. Supports changing the repository name, description, homepage, path, public or private state, default branch, whether LFS is enabled… |
| 13 | Delete a repository | DELETE /api/v5/repos/{owner}/{repo} |
Deletes the specified repository. The target repository is located by its namespace address and repository path; on success it returns an empty object, and if the repository does not exist it returns the corresponding error… |
| 14 | Modify project code approval settings | PUT /api/v5/repos/{owner}/{repo}/reviewer |
Call this endpoint to modify the project code approval settings. |
| 15 | Archive a repository | PUT /api/v5/org/{org}/repo/{repo}/status |
Updates the archive status of the specified repository. By setting the repository state to archived or unarchived, it archives and restores the repository. |
| 16 | Transfer a repository | POST /api/v5/org/{org}/projects/{repo}/transfer |
Transfers the specified repository to a target organization, changing the organization it belongs to; after a successful transfer the repository is managed by the target organization. |
| 17 | Get the permission mode of a project | GET /api/v5/repos/{owner}/{repo}/transition |
Call this endpoint to get the permission mode of the project. |
| 18 | Update the permission mode of a repository | PUT /api/v5/repos/{owner}/{repo}/transition |
Call this endpoint to update the permission mode of the repository. |
| 19 | Set project push rules | PUT /api/v5/repos/{owner}/{repo}/push_config |
Call this endpoint to set the project push rules. |
| 20 | Get project push rules | GET /api/v5/repos/{owner}/{repo}/push_config |
Call this endpoint to get the project push rules. |
| 21 | Fork a repository | POST /api/v5/repos/{owner}/{repo}/forks |
Copies (forks) the specified repository to a target namespace. You can specify the organization namespace, the new repository name, and its path; when omitted, the repository is copied to the user's personal namespace… |
| 22 | View repository forks | GET /api/v5/repos/{owner}/{repo}/forks |
Lists all fork repositories of the specified repository, queried by the repository's namespace address and path, and supports sorting by fork time… |
| 23 | Upload an image | POST /api/v5/repos/{owner}/{repo}/img/upload |
Uploads an image to the specified repository. The request body contains the Base64-encoded image content and the file name; on success it returns the image… |
| 24 | Upload a file | POST /api/v5/repos/*/*/file/upload |
Uploads an attachment to the specified repository; the file size limit is 20M. On success it returns the file's relative path and full access URL for later access or… |
| 25 | List users who are watching the repository | GET /api/v5/repos/{owner}/{repo}/subscribers |
Call this endpoint to list the users who are watching the repository. |
| 26 | List users who have starred the repository | GET /api/v5/repos/{owner}/{repo}/stargazers |
Call this endpoint to list the users who have starred the repository. |
| 27 | Update repository settings | PUT /api/v5/repos/{owner}/{repo}/repo_settings |
Call this endpoint to update the repository settings. |
| 28 | Get repository settings | GET /api/v5/repos/{owner}/{repo}/repo_settings |
Call this endpoint to get the repository settings. |
| 29 | Get pull request settings | GET /api/v5/repos/{owner}/{repo}/pull_request_settings |
Retrieves the pull request settings of the specified repository, including merge modes, review and approval requirements, squash merge options,… |
| 30 | Update pull request settings | PUT /api/v5/repos/{owner}/{repo}/pull_request_settings |
Updates the pull request settings of the specified repository. You can configure merge methods, the number of reviewers and approvers, pipeline and discussion merge conditions, sq… |
| 31 | Update project member roles | PUT /api/v5/repos/{owner}/{repo}/members/{username} |
Updates the role permission of the specified member in the specified repository, adjusting the member's position in the repository by setting a permission level such as participant, developer, maintainer, or a custom role… |
| 32 | Transfer a repository | POST /api/v5/repos/{owner}/{repo}/transfer |
Call this endpoint to transfer a repository. |
| 33 | Get project custom roles | GET /api/v5/repos/{owner}/{repo}/customized_roles |
Retrieves the custom role list of the specified repository (project), returning roles with the role name, permission level, member count, creation time, and update time… |
| 34 | Download count statistics | GET /api/v5/repos/{owner}/{repo}/download_statistics |
Queries the download counts of the specified repository within a date range. You can set the start and end dates and the sort order; the response returns daily download details and the statistics period… |
| 35 | Get a raw file | GET /api/v5/repos/{owner}/{repo}/raw/{path} |
Call this endpoint to retrieve a raw file. |
| 36 | Get repository contributor statistics | GET /api/v5/repos/{owner}/{repo}/contributors/statistic |
Retrieves contributor statistics of the specified repository, returning each contributor's added lines, deleted lines, total changes, and commit counts, along with daily… |
| 37 | Get repository activity | GET /api/v5/repos/{owner}/{repo}/events |
Retrieves the activity (event) list of the specified repository. Supports filtering by event type, actor, and date range, and returns event details page by page. |
| 38 | Query fork synchronization status | GET /api/v5/repos/{owner}/{repo}/sync_repo |
Call this endpoint to query the synchronization status of a forked repository. |
| 39 | Sync a fork with its source repository | PUT /api/v5/repos/{owner}/{repo}/sync_repo |
Call this endpoint to synchronize a forked repository with its source repository. |
| 40 | Query the list of remote mirrors pushed by the repository | GET /api/v5/repos/{owner}/{repo}/push_remote_mirrors |
Call this endpoint to query the list of remote mirrors the repository pushes to. |
| 41 | Get the repository license agreement | GET /api/v5/repos/{owner}/{repo}/license |
Retrieves the license agreement of the specified repository, returning the license file's name, path, size, access URL, content, and encoding, together with the license's SP… |
| 42 | Get the CLA list of a repository | GET /api/v5/repos/{owner}/{repo}/clas |
Retrieves the CLA (Contributor License Agreement) list of the specified repository, returning the contributor license agreements configured for the repository, including each agreement's name and ID… |
| 43 | Configure project CLA | PUT /api/v5/repos/{owner}/{repo}/cla |
Configures the project CLA: pass cla_id to enable and select a specific CLA, or omit it to disable the project CLA configuration; also supports setting… |
| 44 | Get the remote mirror configuration information of the repository | GET /api/v5/repos/{owner}/{repo}/repo_remote_mirror |
Call this endpoint to get the remote mirror configuration information of the repository. |
Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc