Repositories

无闻 edited this page Jun 13, 2018 · 26 revisions

Repositories

Search repositories

GET /repos/search
Parameters
Name Type Description
q string Required Keyword of username
uid int User ID to specify search whose repositories. Default is 0 and search all repositories
limit int Limit number of search results. Default is 10
page int Page number. Default is 1
Example
$ curl https://try.gogs.io/api/v1/repos/search?q=u&uid=1&limit=5
Response
Status: 200 OK
Content-Type: application/json
{
  "data": [
    {
      "id": 1717,
      "owner": {
        "id": 0,
        "username": "",
        "full_name": "",
        "email": "",
        "avatar_url": ""
      },
      "full_name": "unknwon/Issue-966",
      "private": false,
      "fork": false,
      "html_url": "",
      "clone_url": "",
      "ssh_url": "",
      "permissions": {
        "admin": false,
        "push": false,
        "pull": false
      }
    },
    {
      "id": 154,
      "owner": {
        "id": 0,
        "username": "",
        "full_name": "",
        "email": "",
        "avatar_url": ""
      },
      "full_name": "unknwon/issue935",
      "private": false,
      "fork": false,
      "html_url": "",
      "clone_url": "",
      "ssh_url": "",
      "permissions": {
        "admin": false,
        "push": false,
        "pull": false
      }
    }
  ],
  "ok": true
}

List your repositories

List repositories that are accessible to the authenticated user.

This includes repositories owned by the authenticated user, repositories where the authenticated user is a collaborator, and repositories that the authenticated user has access to through an organization membership.

GET /user/repos
Response
Status: 200 OK
Content-Type: application/json
[
  {
    "id": 2,
    "owner": {
      "id": 1,
      "username": "unknwon",
      "full_name": "",
      "email": "u@gogs.io",
      "avatar_url": "/avatars/1"
    },
    "full_name": "unknwon/macaron",
    "private": false,
    "fork": false,
    "html_url": "http://localhost:3000/unknwon/macaron",
    "clone_url": "http://localhost:3000/unknwon/macaron.git",
    "ssh_url": "jiahuachen@localhost:unknwon/macaron.git",
    "permissions": {
      "admin": true,
      "push": true,
      "pull": true
    }
  },
  {
    "id": 8,
    "owner": {
      "id": 2,
      "username": "org1",
      "full_name": "org1",
      "email": "org1@org.com",
      "avatar_url": "/avatars/2"
    },
    "full_name": "org1/gogs",
    "private": false,
    "fork": false,
    "html_url": "http://localhost:3000/org1/gogs",
    "clone_url": "http://localhost:3000/org1/gogs.git",
    "ssh_url": "jiahuachen@localhost:org1/gogs.git",
    "permissions": {
      "admin": true,
      "push": true,
      "pull": true
    }
  }
]

List user repositories

List public repositories for the specified user.

GET /users/:username/repos

List organization repositories

List repositories that are accessible to the authenticated user.

GET /orgs/:orgname/repos

Create

Create a new repository for the authenticated user.

POST /user/repos

Create a new repository in this organization. The authenticated user must be a owner of the specified organization.

POST /org/:org/repos
Parameters
Name Type Description
name string Required The name of the repository
description string A short description of the repository
private bool Either true to create a private repository, or false to create a public one. Default is false
auto_init bool Pass true to create an initial commit with README, .gitignore and LICENSE. Default is false
gitignores string Desired language .gitignore templates to apply. Use the name of the templates. For example, "Go" or "Go,SublimeText".
license string Desired LICENSE template to apply. Use the name of the template. For example, "Apache v2 License" or "MIT License".
readme string Desired README template to apply. Use the name of the template. Default is Default
Litte notes on README template

If you have created file on your corresponding custom/conf/readme/My README, then use "My README".

Currently, you can use following placeholder for corresponding values of repository:

  • {Name}: Repository name
  • {Description}: Repository description
  • {CloneURL.SSH}: Repository SSH clone address
  • {CloneURL.HTTPS}: Repository HTTP/HTTPS clone address
Example
{
  "name": "Hello-World",
  "description": "This is your first repository",
  "private": false
}
Response
Status: 201 Created
Content-Type: application/json
{
  "id": 27,
  "owner": {
    "id": 1,
    "username": "unknwon",
    "full_name": "",
    "email": "u@gogs.io",
    "avatar_url": "/avatars/1"
  },
  "full_name": "unknwon/Hello-World",
  "private": false,
  "fork": false,
  "html_url": "http://localhost:3000/unknwon/Hello-World",
  "clone_url": "http://localhost:3000/unknwon/hello-world.git",
  "ssh_url": "jiahuachen@localhost:unknwon/hello-world.git",
  "permissions": {
    "admin": true,
    "push": true,
    "pull": true
  }
}

Migrate

Migrate a repository from other Git hosting sources for the authenticated user.

POST /repos/migrate

To migrate a repository for a organization, the authenticated user must be a owner of the specified organization.

Parameters
Name Type Description
clone_addr string Required Remote Git address (HTTP/HTTPS URL or local path)
auth_username string Authorization username
auth_password string Authorization password
uid int Required User ID who takes ownership of this repository
repo_name string Required Repository name
mirror bool Repository will be a mirror. Default is false
private bool Repository will be private. Default is false
description string Repository description
Example
{
  "clone_addr": "https://github.com/Unknwon/macaron",
  "uid": 1,
  "repo_name": "hello-macaron"
}
Response
Status: 201 Created
Content-Type: application/json
{
  "id": 19,
  "owner": {
    "id": 1,
    "username": "unknwon",
    "full_name": "",
    "email": "u@gogs.io",
    "avatar_url": "//1.gravatar.com/avatar/d8b2871cdac01b57bbda23716cc03b96"
  },
  "full_name": "unknwon/hello-macaron",
  "private": false,
  "fork": false,
  "html_url": "http://localhost:3000/unknwon/hello-macaron",
  "clone_url": "http://localhost:3000/unknwon/hello-macaron.git",
  "ssh_url": "unknwon@localhost:unknwon/hello-macaron.git",
  "permissions": {
    "admin": true,
    "push": true,
    "pull": true
  }
}

Get

Get information of a single repository.

GET /repos/:owner/:repo
Response
Status: 200 OK
Content-Type: application/json
{
  "id": 19,
  "owner": {
    "id": 1,
    "username": "unknwon",
    "full_name": "",
    "email": "u@gogs.io",
    "avatar_url": "//1.gravatar.com/avatar/d8b2871cdac01b57bbda23716cc03b96"
  },
  "full_name": "unknwon/hello-macaron",
  "private": false,
  "fork": false,
  "html_url": "http://localhost:3000/unknwon/hello-macaron",
  "clone_url": "http://localhost:3000/unknwon/hello-macaron.git",
  "ssh_url": "unknwon@localhost:unknwon/hello-macaron.git",
  "permissions": {
    "admin": true,
    "push": true,
    "pull": true
  }
}

Delete

Deleting a repository requires owner access of repository.

DELETE /repos/:owner/:repo
Response
Status: 204 No Content

List Branches

GET /repos/:owner/:repo/branches
Response
Status: 200 OK
Content-Type: application/json
[
   {
      "name":"master",
      "commit":{
         "id":"c1c220c4dd6df895965a02b8be575c5e2f78dfd1",
         "message":"A commit message. \n",
         "url":"Not implemented",
         "author":{
            "name":"Author Name",
            "email":"author@email.com",
            "username":""
         }
      }
   },
   {
      "name":"second-branch",
      "commit":{
         "id":"0a0fdf63c23af6a2836c426c5284136015ec2996",
         "message":"A second commit message.\n",
         "url":"Not implemented",
         "author":{
            "name":"Author Name",
            "email":"author@email.com",
            "username":""
         }
      }
   }
]

Get Branch

GET /repos/:owner/:repo/branches/:branch
Response
Status: 200 OK
Content-Type: application/json
{
   "name":":branchname",
   "commit":{
      "id":"0a0fdf63c23af6a2836c426c5284136015ec2996",
      "message":"A second commit message.\n",
      "url":"Not implemented",
      "author":{
         "name":"Author Name",
         "email":"author@email.com",
         "username":""
      }
   }
}

Mirror Sync

Add mirror repository to sync queue on behalf of the authenticated user. If the repository is not a mirror, 404 will be returned.

POST /repos/:owner/:repo/mirror-sync
Response
Status: 202 Accepted
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.