Esta versión de GitHub Enterprise se discontinuó el 2021-06-09. No se realizarán lanzamientos de patch, ni siquiera para problemas de seguridad críticos. Para obtener un mejor desempeño, más seguridad y nuevas características, actualiza a la última versión de GitHub Enterprise. Para obtener ayuda con la actualización, contacta al soporte de GitHub Enterprise.

Administración de GitHub Enterprise

You can use these GitHub Enterprise Cloud endpoints to administer your enterprise account.

URL de las Terminales

Las terminales de la API de REST—excepto aquellas API de Consola de Administración—llevan un prefijo con la siguiente URL:

http(s)://hostname/api/v3/

Las terminales de la API de Consola de Administración solo llevan un prefijo con un nombre de host:

http(s)://hostname/

Autenticación

Las terminales de la API para tu instalación de GitHub Enterprise acceptan los mismos métodos de autenticación que los de la API de GitHub.com. Puedes autenticarte con Tokens de OAuth (que se pueden crear utilizando la API de Autorizaciones) o con autenticación básica. Los tokens de OAuth deben tener el alcance de OAuth de site_admin cuando se utilicen con las terminales específicas de la empresa.

Solo puede accederse a las terminales de la API para la administración empresarial si se trata de administradores de sitio de GitHub Enterprise, excepto por la API de Consola de Administración, la cual requiere la contraseña de la Consola de Administración.

Información de la versión

La versión actual de una instancia de GitHub Enterprise se devuelve en el encabezado de respuesta de todas las API: X-GitHub-Enterprise-Version: enterprise-server@2.21.0 También puedes leer la versión actual si llamas a la terminal de meta.

Estadísticas de los Administradores

La API de estadísticas de los administradores proporciona diversas métricas sobre tu instalación. Solo se encuentra disponible para los administradores de sitio autenticados. Los usuarios normales recibirán una respuesta 404 si intentan acceder a ella.

get /enterprise/stats/all

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/all
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/all')

Response

Status: 200 OK
{
  "repos": {
    "total_repos": 212,
    "root_repos": 194,
    "fork_repos": 18,
    "org_repos": 51,
    "total_pushes": 3082,
    "total_wikis": 15
  },
  "hooks": {
    "total_hooks": 27,
    "active_hooks": 23,
    "inactive_hooks": 4
  },
  "pages": {
    "total_pages": 36
  },
  "orgs": {
    "total_orgs": 33,
    "disabled_orgs": 0,
    "total_teams": 60,
    "total_team_members": 314
  },
  "users": {
    "total_users": 254,
    "admin_users": 45,
    "suspended_users": 21
  },
  "pulls": {
    "total_pulls": 86,
    "merged_pulls": 60,
    "mergeable_pulls": 21,
    "unmergeable_pulls": 3
  },
  "issues": {
    "total_issues": 179,
    "open_issues": 83,
    "closed_issues": 96
  },
  "milestones": {
    "total_milestones": 7,
    "open_milestones": 6,
    "closed_milestones": 1
  },
  "gists": {
    "total_gists": 178,
    "private_gists": 151,
    "public_gists": 25
  },
  "comments": {
    "total_commit_comments": 6,
    "total_gist_comments": 28,
    "total_issue_comments": 366,
    "total_pull_request_comments": 30
  }
}

get /enterprise/stats/comments

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/comments
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/comments')

Response

Status: 200 OK

get /enterprise/stats/gists

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/gists
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/gists')

Response

Status: 200 OK

get /enterprise/stats/hooks

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/hooks')

Response

Status: 200 OK

get /enterprise/stats/issues

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/issues
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/issues')

Response

Status: 200 OK

get /enterprise/stats/milestones

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/milestones
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/milestones')

Response

Status: 200 OK

get /enterprise/stats/orgs

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/orgs
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/orgs')

Response

Status: 200 OK

get /enterprise/stats/pages

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/pages
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/pages')

Response

Status: 200 OK

get /enterprise/stats/pulls

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/pulls
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/pulls')

Response

Status: 200 OK

get /enterprise/stats/repos

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/repos
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/repos')

Response

Status: 200 OK

get /enterprise/stats/users

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/stats/users
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/users')

Response

Status: 200 OK

Webhooks globales

Los webhooks globales se instalan en una instancia de GitHub Enterprise. Puedes utilizar los webhooks globales para controlar, responder o aplicar reglas automáticamente para la administración de usuarios, organizaciones, equipos y repositorios en tu instancia. Los webhooks globales se pueden suscribir a los tipos de evento para organizaciones, usuarios, repositorios, equipos, miembros, membrecías, bifuraciones, y pings.

Esta API solo se encuentra disponible para los administradores de sitio autenticados. Los usuarios normales recibirán una respuesta 404 si intentan acceder a ella. Para aprender cómo configurar los webhooks globales, consulta la sección Acerca de los webhooks globales.

get /admin/hooks

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

accept string header

This API is under preview and subject to change.

Default: application/vnd.github.superpro-preview+json
per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/hooks', {
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Response

Status: 200 OK
[
  {
    "type": "Global",
    "id": 1,
    "name": "web",
    "active": true,
    "events": [
      "organization",
      "user"
    ],
    "config": {
      "url": "https://example.com",
      "content_type": "json",
      "insecure_ssl": "0",
      "secret": "********"
    },
    "updated_at": "2017-12-07T00:14:59Z",
    "created_at": "2017-12-07T00:14:59Z",
    "url": "https://api.github.com/admin/hooks/1",
    "ping_url": "https://api.github.com/admin/hooks/1/pings"
  }
]

Aviso de previsualización

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️El encabezado es requerido.

post /admin/hooks

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

accept string header

This API is under preview and subject to change.

Default: application/vnd.github.superpro-preview+json
name string body

Required. Must be passed as "web".

config object body

Required. Key/value pairs to provide settings for this webhook.

Properties of the config object
url (string)

Required. The URL to which the payloads will be delivered.

content_type (string)

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secret (string)

If provided, the secret will be used as the key to generate the HMAC hex digest value in the X-Hub-Signature header.

insecure_ssl (string)

Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.

events array of strings body

The events that trigger this webhook. A global webhook can be triggered by user and organization events. Default: user and organization.

active boolean body

Determines if notifications are sent when the webhook is triggered. Set to true to send notifications.

Default: true

Ejemplos de código

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks \
  -d '{"name":"name","config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl"}}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/hooks', {
  name: 'name',
  config: {
    url: 'url',
    content_type: 'content_type',
    secret: 'secret',
    insecure_ssl: 'insecure_ssl'
  },
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Response

Status: 201 Created
{
  "type": "Global",
  "id": 1,
  "name": "web",
  "active": true,
  "events": [
    "organization",
    "user"
  ],
  "config": {
    "url": "https://example.com",
    "content_type": "json",
    "insecure_ssl": "0",
    "secret": "********"
  },
  "updated_at": "2017-12-07T00:14:59Z",
  "created_at": "2017-12-07T00:14:59Z",
  "url": "https://api.github.com/admin/hooks/1",
  "ping_url": "https://api.github.com/admin/hooks/1/pings"
}

Aviso de previsualización

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️El encabezado es requerido.

get /admin/hooks/{hook_id}

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

accept string header

This API is under preview and subject to change.

Default: application/vnd.github.superpro-preview+json
hook_id integer path

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/hooks/{hook_id}', {
  hook_id: 42,
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Response

Status: 200 OK
{
  "type": "Global",
  "id": 1,
  "name": "web",
  "active": true,
  "events": [
    "organization",
    "user"
  ],
  "config": {
    "url": "https://example.com",
    "content_type": "json",
    "insecure_ssl": "0",
    "secret": "********"
  },
  "updated_at": "2017-12-07T00:14:59Z",
  "created_at": "2017-12-07T00:14:59Z",
  "url": "https://api.github.com/admin/hooks/1",
  "ping_url": "https://api.github.com/admin/hooks/1/pings"
}

Aviso de previsualización

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️El encabezado es requerido.

Update a global webhook

Parameters that are not provided will be overwritten with the default value or removed if no default exists.

patch /admin/hooks/{hook_id}

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

accept string header

This API is under preview and subject to change.

Default: application/vnd.github.superpro-preview+json
hook_id integer path
config object body

Key/value pairs to provide settings for this webhook.

Properties of the config object
url (string)

Required. The URL to which the payloads will be delivered.

content_type (string)

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secret (string)

If provided, the secret will be used as the key to generate the HMAC hex digest value in the X-Hub-Signature header.

insecure_ssl (string)

Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.

events array of strings body

The events that trigger this webhook. A global webhook can be triggered by user and organization events. Default: user and organization.

active boolean body

Determines if notifications are sent when the webhook is triggered. Set to true to send notifications.

Default: true

Ejemplos de código

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks/42 \
  -d '{"config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl"}}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/hooks/{hook_id}', {
  hook_id: 42,
  config: {
    url: 'url',
    content_type: 'content_type',
    secret: 'secret',
    insecure_ssl: 'insecure_ssl'
  },
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Response

Status: 200 OK
{
  "type": "Global",
  "id": 1,
  "name": "web",
  "active": true,
  "events": [
    "organization"
  ],
  "config": {
    "url": "https://example.com",
    "content_type": "form",
    "insecure_ssl": "0"
  },
  "updated_at": "2017-12-07T00:14:59Z",
  "created_at": "2017-12-07T00:14:59Z",
  "url": "https://api.github.com/admin/hooks/1",
  "ping_url": "https://api.github.com/admin/hooks/1/pings"
}

Aviso de previsualización

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️El encabezado es requerido.

delete /admin/hooks/{hook_id}

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

accept string header

This API is under preview and subject to change.

Default: application/vnd.github.superpro-preview+json
hook_id integer path

Ejemplos de código

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/hooks/{hook_id}', {
  hook_id: 42,
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Response

Status: 204 No Content

Aviso de previsualización

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️El encabezado es requerido.

Ping a global webhook

This will trigger a ping event to be sent to the webhook.

post /admin/hooks/{hook_id}/pings

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

accept string header

This API is under preview and subject to change.

Default: application/vnd.github.superpro-preview+json
hook_id integer path

Ejemplos de código

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.superpro-preview+json" \
  http(s)://{hostname}/api/v3/admin/hooks/42/pings
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/hooks/{hook_id}/pings', {
  hook_id: 42,
  mediaType: {
    previews: [
      'superpro'
    ]
  }
})

Response

Status: 204 No Content

Aviso de previsualización

The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json
☝️El encabezado es requerido.

LDAP

Puedes utilizar la API de LDAP para actualizar las relaciones de cuenta entre un usuario de Servidor de GitHub Enterprise o un equipo y su entrada enlazada de LDAP o poner en cola una sincronización nueva.

Con las terminales de mapeo de LDAP, puedes actualizar el Nombre Distintivo (DN, por sus siglas en inglés) al cual mapea un usuario o equipo. Nota que las terminales de LDAP generalmente solo son efectivas si tu aplicativo de Servidor de GitHub Enterprise habilitó la sincronización con LDAP. La terminal de mapeo de LDAP para actualización para un usuario puede utilizarse cuando se habilita LDAP, aún si la sincronización con LDAP está inhabilitada.

Update LDAP mapping for a team

Updates the distinguished name (DN) of the LDAP entry to map to a team. LDAP synchronization must be enabled to map LDAP entries to a team. Use the Create a team endpoint to create a team with LDAP mapping.

You can also update the LDAP mapping of a child team.

patch /admin/ldap/teams/{team_id}/mapping

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

team_id integer path
ldap_dn string body

The distinguished name (DN) of the LDAP entry to map to a team.

Ejemplos de código

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/ldap/teams/42/mapping \
  -d '{"ldap_dn":"ldap_dn"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/ldap/teams/{team_id}/mapping', {
  team_id: 42,
  ldap_dn: 'ldap_dn'
})

Response

Status: 200 OK
{
  "ldap_dn": "cn=Enterprise Ops,ou=teams,dc=github,dc=com",
  "id": 1,
  "node_id": "MDQ6VGVhbTE=",
  "url": "https://api.github.com/teams/1",
  "html_url": "https://github.com/orgs/github/teams/justice-league",
  "name": "Justice League",
  "slug": "justice-league",
  "description": "A great team.",
  "privacy": "closed",
  "permission": "admin",
  "members_url": "https://api.github.com/teams/1/members{/member}",
  "repositories_url": "https://api.github.com/teams/1/repos",
  "parent": null
}

Sync LDAP mapping for a team

Note that this API call does not automatically initiate an LDAP sync. Rather, if a 201 is returned, the sync job is queued successfully, and is performed when the instance is ready.

post /admin/ldap/teams/{team_id}/sync

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

team_id integer path

Ejemplos de código

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/ldap/teams/42/sync
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/ldap/teams/{team_id}/sync', {
  team_id: 42
})

Response

Status: 201 Created
{
  "status": "queued"
}

patch /admin/ldap/users/{username}/mapping

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path
ldap_dn string body

The distinguished name (DN) of the LDAP entry to map to a team.

Ejemplos de código

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/ldap/users/USERNAME/mapping \
  -d '{"ldap_dn":"ldap_dn"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/ldap/users/{username}/mapping', {
  username: 'username',
  ldap_dn: 'ldap_dn'
})

Response

Status: 200 OK
{
  "ldap_dn": "uid=asdf,ou=users,dc=github,dc=com",
  "login": "octocat",
  "id": 1,
  "node_id": "MDQ6VXNlcjE=",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "gravatar_id": "",
  "url": "https://api.github.com/users/octocat",
  "html_url": "https://github.com/octocat",
  "followers_url": "https://api.github.com/users/octocat/followers",
  "following_url": "https://api.github.com/users/octocat/following{/other_user}",
  "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
  "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
  "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
  "organizations_url": "https://api.github.com/users/octocat/orgs",
  "repos_url": "https://api.github.com/users/octocat/repos",
  "events_url": "https://api.github.com/users/octocat/events{/privacy}",
  "received_events_url": "https://api.github.com/users/octocat/received_events",
  "type": "User",
  "site_admin": false,
  "name": "monalisa octocat",
  "company": "GitHub",
  "blog": "https://github.com/blog",
  "location": "San Francisco",
  "email": "octocat@github.com",
  "hireable": false,
  "bio": "There once was...",
  "twitter_username": "monatheoctocat",
  "public_repos": 2,
  "public_gists": 1,
  "followers": 20,
  "following": 0,
  "created_at": "2008-01-14T04:33:35Z",
  "updated_at": "2008-01-14T04:33:35Z",
  "private_gists": 81,
  "total_private_repos": 100,
  "owned_private_repos": 100,
  "disk_usage": 10000,
  "collaborators": 8,
  "two_factor_authentication": true,
  "plan": {
    "name": "Medium",
    "space": 400,
    "private_repos": 20,
    "collaborators": 0
  }
}

Sync LDAP mapping for a user

Note that this API call does not automatically initiate an LDAP sync. Rather, if a 201 is returned, the sync job is queued successfully, and is performed when the instance is ready.

post /admin/ldap/users/{username}/sync

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path

Ejemplos de código

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/ldap/users/USERNAME/sync
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/ldap/users/{username}/sync', {
  username: 'username'
})

Response

Status: 201 Created
{
  "status": "queued"
}

Licencia

La API de licencias proporciona información sobre tu licencia empresarial. Solo se encuentra disponible para los administradores de sitio autenticados. Los usuarios normales recibirán una respuesta 404 si intentan acceder a ella.

get /enterprise/settings/license

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/enterprise/settings/license
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/settings/license')

Response

Status: 200 OK
{
  "seats": 1400,
  "seats_used": 1316,
  "seats_available": 84,
  "kind": "standard",
  "days_until_expiration": 365,
  "expire_at": "2016/02/06 12:41:52 -0600"
}

Consola de administración

La API de la Consola de Administración te ayuda a administrar tu Servidor de GitHub Enterprise instalación.

Debes configurar el número de puerto explícitamente cuando haces llamadas de la API hacia la Consola de Administración. Si se habilita el TLS en tu instancia empresarial, el número de puerto es 8443; de lo contrario, el número de puerto será 8080.

Si no quieres proporcionar un número de puerto, necesitarás configurar tu herramienta para seguir automáticamente las redirecciones.

También necesitas agregar el marcador -k cuando utilices curl, ya que Servidor de GitHub Enterprise utiliza un certificado auto-firmado antes de que agregues tu propio certificado TLS.

Autenticación

Necesitas pasar tu Contraseña de la Consola de Administración como un token de autenticación para cada terminal de la API de ésta, con excepción de /setup/api/start.

Utiliza el parámetro de api_key para enviar este token con cada solicitud. Por ejemplo:

$ curl -L 'https://hostname:admin_port/setup/api?api_key=your-amazing-password'

También puedes utilizar la autenticación HTTP estándar para enviar este token. Por ejemplo:

$ curl -L 'https://api_key:your-amazing-password@hostname:admin_port/setup/api'

Get the configuration status

This endpoint allows you to check the status of the most recent configuration process:

Note that you may need to wait several seconds after you start a process before you can check its status.

The different statuses are:

StatusDescription
PENDINGThe job has not started yet
CONFIGURINGThe job is running
DONEThe job has finished correctly
FAILEDThe job has finished unexpectedly
get /setup/api/configcheck

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/configcheck
JavaScript (@octokit/core.js)
await octokit.request('GET /setup/api/configcheck')

Response

Status: 200 OK
{
  "status": "running",
  "progress": [
    {
      "status": "DONE",
      "key": "Appliance core components"
    },
    {
      "status": "DONE",
      "key": "GitHub utilities"
    },
    {
      "status": "DONE",
      "key": "GitHub applications"
    },
    {
      "status": "CONFIGURING",
      "key": "GitHub services"
    },
    {
      "status": "PENDING",
      "key": "Reloading appliance services"
    }
  ]
}

Start a configuration process

This endpoint allows you to start a configuration process at any time for your updated settings to take effect:

post /setup/api/configure

Ejemplos de código

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/configure
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/configure')

Response

Status: 202 Accepted

Get the maintenance status

Check your installation's maintenance status:

get /setup/api/maintenance

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/maintenance
JavaScript (@octokit/core.js)
await octokit.request('GET /setup/api/maintenance')

Response

Status: 200 OK
{
  "status": "scheduled",
  "scheduled_time": "Tuesday, January 22 at 15:34 -0800",
  "connection_services": [
    {
      "name": "git operations",
      "number": 0
    },
    {
      "name": "mysql queries",
      "number": 233
    },
    {
      "name": "resque jobs",
      "number": 54
    }
  ]
}

Enable or disable maintenance mode

Note: The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.

post /setup/api/maintenance

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

maintenance string body

Required. A JSON string with the attributes enabled and when.

The possible values for enabled are true and false. When it's false, the attribute when is ignored and the maintenance mode is turned off. when defines the time period when the maintenance was enabled.

The possible values for when are now or any date parseable by mojombo/chronic.

Ejemplos de código

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/maintenance \
  --data-urlencode maintenance=maintenance
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/maintenance', {
  maintenance: 'maintenance'
})

Response

Status: 200 OK
{
  "status": "scheduled",
  "scheduled_time": "Tuesday, January 22 at 15:34 -0800",
  "connection_services": [
    {
      "name": "git operations",
      "number": 0
    },
    {
      "name": "mysql queries",
      "number": 233
    },
    {
      "name": "resque jobs",
      "number": 54
    }
  ]
}

get /setup/api/settings

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/settings
JavaScript (@octokit/core.js)
await octokit.request('GET /setup/api/settings')

Response

Status: 200 OK
{
  "enterprise": {
    "private_mode": false,
    "public_pages": false,
    "subdomain_isolation": true,
    "signup_enabled": false,
    "github_hostname": "ghe.local",
    "identicons_host": "dotcom",
    "http_proxy": null,
    "auth_mode": "default",
    "expire_sessions": false,
    "admin_password": null,
    "configuration_id": 1401777404,
    "configuration_run_count": 4,
    "avatar": {
      "enabled": false,
      "uri": ""
    },
    "customer": {
      "name": "GitHub",
      "email": "stannis@themannis.biz",
      "uuid": "af6cac80-e4e1-012e-d822-1231380e52e9",
      "secret_key_data": "-----BEGIN PGP PRIVATE KEY BLOCK-----\nVersion: GnuPG v1.4.10 (GNU/Linux)\n\nlQcYBE5TCgsBEACk4yHpUcapplebaumBMXYMiLF+nCQ0lxpx...\n-----END PGP PRIVATE KEY BLOCK-----\n",
      "public_key_data": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: GnuPG v1.4.10 (GNU/Linux)\n\nmI0ETqzZYgEEALSe6snowdenXyqvLfSQ34HWD6C7....\n-----END PGP PUBLIC KEY BLOCK-----\n"
    },
    "license": {
      "seats": 0,
      "evaluation": false,
      "perpetual": false,
      "unlimited_seating": true,
      "support_key": "ssh-rsa AAAAB3N....",
      "ssh_allowed": true,
      "cluster_support": false,
      "expire_at": "2016-04-27T00:00:00-07:00"
    },
    "github_ssl": {
      "enabled": false,
      "cert": null,
      "key": null
    },
    "ldap": {
      "host": null,
      "port": 0,
      "base": [],
      "uid": null,
      "bind_dn": null,
      "password": null,
      "method": "Plain",
      "search_strategy": "detect",
      "user_groups": [],
      "admin_group": null,
      "virtual_attribute_enabled": false,
      "recursive_group_search": false,
      "posix_support": true,
      "user_sync_emails": false,
      "user_sync_keys": false,
      "user_sync_interval": 4,
      "team_sync_interval": 4,
      "sync_enabled": false,
      "reconciliation": {
        "user": null,
        "org": null
      },
      "profile": {
        "uid": "uid",
        "name": null,
        "mail": null,
        "key": null
      }
    },
    "cas": {
      "url": null
    },
    "saml": {
      "sso_url": null,
      "certificate": null,
      "certificate_path": null,
      "issuer": null,
      "idp_initiated_sso": false,
      "disable_admin_demote": false
    },
    "github_oauth": {
      "client_id": "12313412",
      "client_secret": "kj123131132",
      "organization_name": "Homestar Runners",
      "organization_team": "homestarrunners/characters"
    },
    "smtp": {
      "enabled": true,
      "address": "smtp.example.com",
      "authentication": "plain",
      "port": "1234",
      "domain": "blah",
      "username": "foo",
      "user_name": "mr_foo",
      "enable_starttls_auto": true,
      "password": "bar",
      "discard-to-noreply-address": true,
      "support_address": "enterprise@github.com",
      "support_address_type": "email",
      "noreply_address": "noreply@github.com"
    },
    "ntp": {
      "primary_server": "0.pool.ntp.org",
      "secondary_server": "1.pool.ntp.org"
    },
    "timezone": null,
    "snmp": {
      "enabled": false,
      "community": ""
    },
    "syslog": {
      "enabled": false,
      "server": null,
      "protocol_name": "udp"
    },
    "assets": null,
    "pages": {
      "enabled": true
    },
    "collectd": {
      "enabled": false,
      "server": null,
      "port": 0,
      "encryption": null,
      "username": null,
      "password": null
    },
    "mapping": {
      "enabled": true,
      "tileserver": null,
      "basemap": "company.map-qsz2zrvs",
      "token": null
    },
    "load_balancer": null
  },
  "run_list": [
    "recipe[enterprise-configure]"
  ]
}

Set settings

For a list of the available settings, see the Get settings endpoint.

Note: The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.

put /setup/api/settings

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

settings string body

Required. A JSON string with the new settings. Note that you only need to pass the specific settings you want to modify. For a list of the available settings, see the Get settings endpoint.

Ejemplos de código

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/settings \
  --data-urlencode settings=settings
JavaScript (@octokit/core.js)
await octokit.request('PUT /setup/api/settings', {
  settings: 'settings'
})

Response

Status: 204 No Content

get /setup/api/settings/authorized-keys

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/settings/authorized-keys
JavaScript (@octokit/core.js)
await octokit.request('GET /setup/api/settings/authorized-keys')

Response

Status: 200 OK
[
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  }
]

Add an authorized SSH key

Note: The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.

post /setup/api/settings/authorized-keys

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

authorized_key string body

Required. The public SSH key.

Ejemplos de código

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/settings/authorized-keys \
  --data-urlencode authorized_key=authorized_key
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/settings/authorized-keys', {
  authorized_key: 'authorized_key'
})

Response

Status: 201 Created
[
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  }
]

Remove an authorized SSH key

Note: The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.

delete /setup/api/settings/authorized-keys

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

authorized_key string body

Required. The public SSH key.

Ejemplos de código

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/settings/authorized-keys \
  --data-urlencode authorized_key=authorized_key
JavaScript (@octokit/core.js)
await octokit.request('DELETE /setup/api/settings/authorized-keys', {
  authorized_key: 'authorized_key'
})

Response

Status: 200 OK
[
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  },
  {
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
    "pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
  }
]

Create a GitHub license

When you boot a GitHub instance for the first time, you can use the following endpoint to upload a license.

Note that you need to POST to /setup/api/configure to start the actual configuration process.

When using this endpoint, your GitHub instance must have a password set. This can be accomplished two ways:

  1. If you're working directly with the API before accessing the web interface, you must pass in the password parameter to set your password.
  2. If you set up your instance via the web interface before accessing the API, your calls to this endpoint do not need the password parameter.

Note: The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.

post /setup/api/start

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

license string body

Required. The content of your .ghl license file.

password string body

You must provide a password only if you are uploading your license for the first time. If you previously set a password through the web interface, you don't need this parameter.

settings string body

An optional JSON string containing the installation settings. For a list of the available settings, see the Get settings endpoint.

Ejemplos de código

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/start \
  --data-urlencode license=license
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/start', {
  license: 'license'
})

Response

Status: 202 Accepted

Upgrade a license

This API upgrades your license and also triggers the configuration process.

Note: The request body for this operation must be submitted as application/x-www-form-urlencoded data. You can submit a parameter value as a string, or you can use a tool such as curl to submit a parameter value as the contents of a text file. For more information, see the curl documentation.

post /setup/api/upgrade

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

license string body

The content of your new .ghl license file.

Ejemplos de código

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/setup/api/upgrade \
  --data-urlencode license=license
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/upgrade', {
  license: 'license'
})

Response

Status: 202 Accepted

Organizaciones

La API de Administración de la organización te permite crear organizaciones en un aplicativo de Servidor de GitHub Enterprise. Solo se encuentra disponible para los administradores de sitio autenticados. Los usuarios normales recibirán una respuesta 404 si intentan acceder a ella.

post /admin/organizations

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

login string body

Required. The organization's username.

admin string body

Required. The login of the user who will manage this organization.

profile_name string body

The organization's display name.

Ejemplos de código

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/organizations \
  -d '{"login":"login","admin":"admin"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/organizations', {
  login: 'login',
  admin: 'admin'
})

Response

Status: 201 Created
{
  "login": "github",
  "id": 1,
  "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
  "url": "https://api.github.com/orgs/github",
  "repos_url": "https://api.github.com/orgs/github/repos",
  "events_url": "https://api.github.com/orgs/github/events",
  "hooks_url": "https://api.github.com/orgs/github/hooks",
  "issues_url": "https://api.github.com/orgs/github/issues",
  "members_url": "https://api.github.com/orgs/github/members{/member}",
  "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "description": "A great organization"
}

patch /admin/organizations/{org}

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
login string body

Required. The organization's new name.

Ejemplos de código

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/organizations/ORG \
  -d '{"login":"login"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/organizations/{org}', {
  org: 'org',
  login: 'login'
})

Response

Status: 202 Accepted
{
  "message": "Job queued to rename organization. It may take a few minutes to complete.",
  "url": "https://<hostname>/api/v3/organizations/1"
}

Ganchos de Pre-recepción de la Organización

La API de Ganchos de Pre-recepción de la Organización te permite ver y modificar la aplicación de dichos ganchos que están disponibles para una organización.

Atributos de objeto

NombreTipoDescripción
name (nombre)secuenciaEl nombre del gancho.
enforcementsecuenciaEl estado de imposición del gancho en este repositorio.
allow_downstream_configurationbooleanSi los repositorios pueden ignorar la imposición o no.
configuration_urlsecuenciaURL para la terminal en donde se configuró la imposición.

Los valores posibles para enforcement son enabled, disabled y testing. El valor disabled indica que el gancho de pre-recepción no se ejecutará. El valor enabled indica que se ejecutará y rechazará cualquier carga que resulte en un estado diferente a zero. El valor testing indica que el script va a ejecutarse pero no va a causar que se rechace ninguna carga.

configuration_url podría ser un enlace a esta terminal o ser la configuración global de este gancho. Solo los administradores de sistema pueden acceder a la configuración global.

List pre-receive hooks for an organization

List all pre-receive hooks that are enabled or testing for this organization as well as any disabled hooks that can be configured at the organization level. Globally disabled pre-receive hooks that do not allow downstream configuration are not listed.

get /orgs/{org}/pre-receive-hooks

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

org string path
per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1
direction string query

One of asc (ascending) or desc (descending).

Default: desc
sort string query

The sort order for the response collection.

Default: created

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/orgs/ORG/pre-receive-hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/pre-receive-hooks', {
  org: 'org',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
[
  {
    "id": 42,
    "name": "Check Commits",
    "enforcement": "disabled",
    "configuration_url": "https://github.example.com/api/v3/admin/pre-receive-hooks/42",
    "allow_downstream_configuration": true
  }
]

Notes

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

get /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

org string path
pre_receive_hook_id integer path

pre_receive_hook_id parameter

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/orgs/ORG/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
  org: 'org',
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "disabled",
  "configuration_url": "https://github.example.com/api/v3/admin/pre-receive-hooks/42",
  "allow_downstream_configuration": true
}

Notes

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

Update pre-receive hook enforcement for an organization

For pre-receive hooks which are allowed to be configured at the org level, you can set enforcement and allow_downstream_configuration

patch /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

org string path
pre_receive_hook_id integer path

pre_receive_hook_id parameter

enforcement string body

The state of enforcement for the hook on this repository.

allow_downstream_configuration boolean body

Whether repositories can override enforcement.

Ejemplos de código

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/orgs/ORG/pre-receive-hooks/42 \
  -d '{"enforcement":"enforcement"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
  org: 'org',
  pre_receive_hook_id: 42,
  enforcement: 'enforcement',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "enabled",
  "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42",
  "allow_downstream_configuration": false
}

Notes

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

Remove pre-receive hook enforcement for an organization

Removes any overrides for this hook at the org level for this org.

delete /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

org string path
pre_receive_hook_id integer path

pre_receive_hook_id parameter

Ejemplos de código

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/orgs/ORG/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
  org: 'org',
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "disabled",
  "configuration_url": "https://github.example.com/api/v3/admin/pre-receive-hooks/42",
  "allow_downstream_configuration": true
}

Notes

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

Ambientes de pre-recepción

La API de Ambientes de Pre-recepción te permite crear, listar, actualizar y borrar ambientes para los ganchos de pre-recepción. Solo se encuentra disponible para los administradores de sitio autenticados. Los usuarios normales recibirán una respuesta 404 si intentan acceder a ella.

Atributos de objeto

Ambiente de pre-recepción

NombreTipoDescripción
name (nombre)secuenciaEl nombre del ambiente como se muestra en la IU.
image_urlsecuenciaLa URL del tarball que se descargará y extraerá.
default_environmentbooleanSi este es el ambiente predeterminado que viene con Servidor de GitHub Enterprise o no.
descargarobjetoEl estado de descarga de este ambiente.
hooks_countnúmeroLa cantidad de ganchos de pre-recepción que utilizan este ambiente.

Descarga del Ambiente de Pre-recepción

NombreTipoDescripción
statesecuenciaEl estado de la mayoría de las descargas recientes.
downloaded_atsecuenciaLa hora en la cual iniciaron la mayoría de las descrgas recientes.
messagesecuenciaCuando algo falla, este tendrá cualquier mensaje de error que se haya producido.

Los valores posibles para state son not_started, in_progress, success, failed.

get /admin/pre-receive-environments

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1
direction string query

One of asc (ascending) or desc (descending).

Default: desc
sort string query Default: created

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-environments', {
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
[
  {
    "id": 1,
    "name": "Default",
    "image_url": "githubenterprise://internal",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1",
    "html_url": "https://github.example.com/admin/pre-receive-environments/1",
    "default_environment": true,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 14,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1/downloads/latest",
      "state": "not_started",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  },
  {
    "id": 2,
    "name": "DevTools Hook Env",
    "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
    "html_url": "https://github.example.com/admin/pre-receive-environments/2",
    "default_environment": false,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 1,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
      "state": "success",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  }
]

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

post /admin/pre-receive-environments

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

name string body

Required. The new pre-receive environment's name.

image_url string body

Required. URL from which to download a tarball of this environment.

Ejemplos de código

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments \
  -d '{"name":"name","image_url":"image_url"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/pre-receive-environments', {
  name: 'name',
  image_url: 'image_url',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 201 Created
{
  "id": 2,
  "name": "DevTools Hook Env",
  "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
  "html_url": "https://github.example.com/admin/pre-receive-environments/2",
  "default_environment": false,
  "created_at": "2016-05-20T11:35:45-05:00",
  "hooks_count": 1,
  "download": {
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
    "state": "not_started",
    "downloaded_at": null,
    "message": null
  }
}

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

get /admin/pre-receive-environments/{pre_receive_environment_id}

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

pre_receive_environment_id integer path

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments/42
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-environments/{pre_receive_environment_id}', {
  pre_receive_environment_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 2,
  "name": "DevTools Hook Env",
  "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
  "html_url": "https://github.example.com/admin/pre-receive-environments/2",
  "default_environment": false,
  "created_at": "2016-05-20T11:35:45-05:00",
  "hooks_count": 1,
  "download": {
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
    "state": "success",
    "downloaded_at": "2016-05-26T07:42:53-05:00",
    "message": null
  }
}

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

Update a pre-receive environment

You cannot modify the default environment. If you attempt to modify the default environment, you will receive a 422 Unprocessable Entity response.

patch /admin/pre-receive-environments/{pre_receive_environment_id}

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

pre_receive_environment_id integer path
name string body

This pre-receive environment's new name.

image_url string body

URL from which to download a tarball of this environment.

Ejemplos de código

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments/42 \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/pre-receive-environments/{pre_receive_environment_id}', {
  pre_receive_environment_id: 42,
  name: 'name',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 2,
  "name": "DevTools Hook Env",
  "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
  "html_url": "https://github.example.com/admin/pre-receive-environments/2",
  "default_environment": false,
  "created_at": "2016-05-20T11:35:45-05:00",
  "hooks_count": 1,
  "download": {
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
    "state": "success",
    "downloaded_at": "2016-05-26T07:42:53-05:00",
    "message": null
  }
}

Client Errors

Status: 422 Unprocessable Entity
{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "PreReceiveEnvironment",
      "code": "custom",
      "message": "Cannot modify or delete the default environment"
    }
  ]
}

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

Delete a pre-receive environment

If you attempt to delete an environment that cannot be deleted, you will receive a 422 Unprocessable Entity response.

The possible error messages are:

  • Cannot modify or delete the default environment
  • Cannot delete environment that has hooks
  • Cannot delete environment when download is in progress
delete /admin/pre-receive-environments/{pre_receive_environment_id}

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

pre_receive_environment_id integer path

Ejemplos de código

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/pre-receive-environments/{pre_receive_environment_id}', {
  pre_receive_environment_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 204 No Content

Client Errors

Status: 422 Unprocessable Entity
{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "PreReceiveEnvironment",
      "code": "custom",
      "message": "Cannot modify or delete the default environment"
    }
  ]
}

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

Start a pre-receive environment download

Triggers a new download of the environment tarball from the environment's image_url. When the download is finished, the newly downloaded tarball will overwrite the existing environment.

If a download cannot be triggered, you will receive a 422 Unprocessable Entity response.

The possible error messages are:

  • Cannot modify or delete the default environment
  • Can not start a new download when a download is in progress
post /admin/pre-receive-environments/{pre_receive_environment_id}/downloads

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

pre_receive_environment_id integer path

Ejemplos de código

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments/42/downloads
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/pre-receive-environments/{pre_receive_environment_id}/downloads', {
  pre_receive_environment_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 202 Accepted
{
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/3/downloads/latest",
  "state": "not_started",
  "downloaded_at": null,
  "message": null
}

Client Errors

Status: 422 Unprocessable Entity
{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "PreReceiveEnvironment",
      "code": "custom",
      "message": "Can not start a new download when a download is in progress"
    }
  ]
}

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

Get the download status for a pre-receive environment

In addition to seeing the download status at the "Get a pre-receive environment" endpoint, there is also this separate endpoint for just the download status.

get /admin/pre-receive-environments/{pre_receive_environment_id}/downloads/latest

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

pre_receive_environment_id integer path

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-environments/42/downloads/latest
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-environments/{pre_receive_environment_id}/downloads/latest', {
  pre_receive_environment_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "url": "https://github.example.com/api/v3/admin/pre-receive-environments/3/downloads/latest",
  "state": "success",
  "downloaded_at": "2016-05-26T07:42:53-05:00",
  "message": null
}

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

Ganchos de pre-recepción

La API de Ganchos Pre-recepción te permite crear, listar, actualizar y borrar los ganchos de pre-recepción. Solo se encuentra disponible para los administradores de sitio autenticados. Los usuarios normales recibirán una respuesta 404 si intentan acceder a ella.

Atributos de objeto

Ganchos de pre-recepción

NombreTipoDescripción
name (nombre)secuenciaEl nombre del gancho.
scriptsecuenciaEl script que ejecuta el gancho.
script_repositoryobjetoEl repositorio de GitHub en donde se mantiene el script.
entornoobjetoEl ambiente de pre-recepción en donde se ejecuta el script.
enforcementsecuenciaEl estado de las imposiciones para este gancho.
allow_downstream_configurationbooleanSi las imposiciones pueden o no ignorarse a nivel de organización o de repositorio.

Los valores posibles para enforcement son enabled, disabled y testing. El valor disabled indica que el gancho de pre-recepción no se ejecutará. El valor enabled indica que se ejecutará y rechazará cualquier carga que resulte en un estado diferente a zero. El valor testing indica que el script va a ejecutarse pero no va a causar que se rechace ninguna carga.

get /admin/pre-receive-hooks

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1
direction string query

One of asc (ascending) or desc (descending).

Default: desc
sort string query

One of created (when the repository was starred) or updated (when it was last pushed to) or name.

Default: created

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-hooks', {
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
[
  {
    "id": 1,
    "name": "Check Commits",
    "enforcement": "disabled",
    "script": "scripts/commmit_check.sh",
    "script_repository": {
      "id": 595,
      "full_name": "DevIT/hooks",
      "url": "https://github.example.com/api/v3/repos/DevIT/hooks",
      "html_url": "https://github.example.com/DevIT/hooks"
    },
    "environment": {
      "id": 2,
      "name": "DevTools Hook Env",
      "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
      "html_url": "https://github.example.com/admin/pre-receive-environments/2",
      "default_environment": false,
      "created_at": "2016-05-20T11:35:45-05:00",
      "hooks_count": 1,
      "download": {
        "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
        "state": "success",
        "downloaded_at": "2016-05-26T07:42:53-05:00",
        "message": null
      }
    },
    "allow_downstream_configuration": false
  }
]

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

post /admin/pre-receive-hooks

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

name string body

Required. The name of the hook.

script string body

Required. The script that the hook runs.

script_repository object body

Required. The GitHub repository where the script is kept.

environment object body

Required. The pre-receive environment where the script is executed.

enforcement string body

The state of enforcement for this hook. default: disabled

allow_downstream_configuration boolean body

Whether enforcement can be overridden at the org or repo level. default: false

Ejemplos de código

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-hooks \
  -d '{"name":"name","script":"script","script_repository":{},"environment":{}}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/pre-receive-hooks', {
  name: 'name',
  script: 'script',
  script_repository: {},
  environment: {},
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 201 Created
{
  "id": 1,
  "name": "Check Commits",
  "enforcement": "disabled",
  "script": "scripts/commmit_check.sh",
  "script_repository": {
    "id": 595,
    "full_name": "DevIT/hooks",
    "url": "https://github.example.com/api/v3/repos/DevIT/hooks",
    "html_url": "https://github.example.com/DevIT/hooks"
  },
  "environment": {
    "id": 2,
    "name": "DevTools Hook Env",
    "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
    "html_url": "https://github.example.com/admin/pre-receive-environments/2",
    "default_environment": false,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 1,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
      "state": "success",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  },
  "allow_downstream_configuration": false
}

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

get /admin/pre-receive-hooks/{pre_receive_hook_id}

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

pre_receive_hook_id integer path

pre_receive_hook_id parameter

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-hooks/{pre_receive_hook_id}', {
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 1,
  "name": "Check Commits",
  "enforcement": "disabled",
  "script": "scripts/commmit_check.sh",
  "script_repository": {
    "id": 595,
    "full_name": "DevIT/hooks",
    "url": "https://github.example.com/api/v3/repos/DevIT/hooks",
    "html_url": "https://github.example.com/DevIT/hooks"
  },
  "environment": {
    "id": 2,
    "name": "DevTools Hook Env",
    "image_url": "https://my_file_server/path/to/devtools_env.tar.gz",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2",
    "html_url": "https://github.example.com/admin/pre-receive-environments/2",
    "default_environment": false,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 1,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest",
      "state": "success",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  },
  "allow_downstream_configuration": false
}

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

patch /admin/pre-receive-hooks/{pre_receive_hook_id}

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

pre_receive_hook_id integer path

pre_receive_hook_id parameter

name string body

The name of the hook.

script string body

The script that the hook runs.

script_repository object body

The GitHub repository where the script is kept.

environment object body

The pre-receive environment where the script is executed.

enforcement string body

The state of enforcement for this hook.

allow_downstream_configuration boolean body

Whether enforcement can be overridden at the org or repo level.

Ejemplos de código

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-hooks/42 \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/pre-receive-hooks/{pre_receive_hook_id}', {
  pre_receive_hook_id: 42,
  name: 'name',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 1,
  "name": "Check Commits",
  "enforcement": "disabled",
  "script": "scripts/commmit_check.sh",
  "script_repository": {
    "id": 595,
    "full_name": "DevIT/hooks",
    "url": "https://github.example.com/api/v3/repos/DevIT/hooks",
    "html_url": "https://github.example.com/DevIT/hooks"
  },
  "environment": {
    "id": 1,
    "name": "Default",
    "image_url": "githubenterprise://internal",
    "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1",
    "html_url": "https://github.example.com/admin/pre-receive-environments/1",
    "default_environment": true,
    "created_at": "2016-05-20T11:35:45-05:00",
    "hooks_count": 1,
    "download": {
      "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1/downloads/latest",
      "state": "success",
      "downloaded_at": "2016-05-26T07:42:53-05:00",
      "message": null
    }
  },
  "allow_downstream_configuration": true
}

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

delete /admin/pre-receive-hooks/{pre_receive_hook_id}

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

pre_receive_hook_id integer path

pre_receive_hook_id parameter

Ejemplos de código

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/admin/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/pre-receive-hooks/{pre_receive_hook_id}', {
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 204 No Content

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

Ganchos de pre-recepción del repositorio

La API de Ganchos de Pre-recepción para Repositorios te permite ver y modificar la imposición de los ganchos de pre-recepción que están disponibles para un repositorio.

Atributos de objeto

NombreTipoDescripción
name (nombre)secuenciaEl nombre del gancho.
enforcementsecuenciaEl estado de imposición del gancho en este repositorio.
configuration_urlsecuenciaURL para la terminal en donde se configuró la imposición.

Los valores posibles para enforcement son enabled, disabled y testing. El valor disabled indica que el gancho de pre-recepción no se ejecutará. El valor enabled indica que se ejecutará y rechazará cualquier carga que resulte en un estado diferente a zero. El valor testing indica que el script va a ejecutarse pero no va a causar que se rechace ninguna carga.

configuration_url podría ser un enlace a este repositorio, al propietario de su organización o a su configuración global. La autorización para acceder a esta terminal en configuration_url se determina a nivel de administrador de sitio o de propietario.

List pre-receive hooks for a repository

List all pre-receive hooks that are enabled or testing for this repository as well as any disabled hooks that are allowed to be enabled at the repository level. Pre-receive hooks that are disabled at a higher level and are not configurable will not be listed.

get /repos/{owner}/{repo}/pre-receive-hooks

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

owner string path
repo string path
per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1
direction string query

One of asc (ascending) or desc (descending).

Default: desc
sort string query Default: created

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/repos/octocat/hello-world/pre-receive-hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/pre-receive-hooks', {
  owner: 'octocat',
  repo: 'hello-world',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
[
  {
    "id": 42,
    "name": "Check Commits",
    "enforcement": "disabled",
    "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42"
  }
]

Notes

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

get /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

owner string path
repo string path
pre_receive_hook_id integer path

pre_receive_hook_id parameter

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/repos/octocat/hello-world/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "disabled",
  "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42"
}

Notes

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

Update pre-receive hook enforcement for a repository

For pre-receive hooks which are allowed to be configured at the repo level, you can set enforcement

patch /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

owner string path
repo string path
pre_receive_hook_id integer path

pre_receive_hook_id parameter

enforcement string body

The state of enforcement for the hook on this repository.

Ejemplos de código

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/repos/octocat/hello-world/pre-receive-hooks/42 \
  -d '{"enforcement":"enforcement"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  pre_receive_hook_id: 42,
  enforcement: 'enforcement',
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Response

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "enabled",
  "configuration_url": "https://github.example.com/api/v3/repos/octocat/hello-world/pre-receive-hooks/42"
}

Notes

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

Remove pre-receive hook enforcement for a repository

Deletes any overridden enforcement on this repository for the specified hook.

Responds with effective values inherited from owner and/or global level.

delete /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}

Parámetros

Name Type In Description
accept string header

This API is under preview and subject to change.Ver aviso de previsualización

owner string path
repo string path
pre_receive_hook_id integer path

pre_receive_hook_id parameter

Ejemplos de código

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.eye-scream-preview+json" \
  http(s)://{hostname}/api/v3/repos/octocat/hello-world/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  pre_receive_hook_id: 42,
  mediaType: {
    previews: [
      'eye-scream'
    ]
  }
})

Responds with effective values inherited from owner and/or global level.

Status: 200 OK
{
  "id": 42,
  "name": "Check Commits",
  "enforcement": "disabled",
  "configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42"
}

Notes

Aviso de previsualización

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview
☝️El encabezado es requerido.

Buscar en los índices

La API de Búsqueda en los índices te permite poner en cola varias tareas de búsqueda en los índices. Solo se encuentra disponible para los administradores de sitio autenticados. Los usuarios normales recibirán una respuesta 404 si intentan acceder a ella.

Usuarios

La API de Administración de usuarios te permite promover, degradar, suspender y dejar de suspender a los usuarios en un aplicativo de Servidor de GitHub Enterprise. Solo se encuentra disponible para los administradores de sitio autenticados. Los usuarios normales recibirán una respuesta 403 si intentan acceder a ella.

get /admin/keys

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1
direction string query

One of asc (ascending) or desc (descending).

Default: desc
sort string query Default: created
since string query

Only show public keys accessed after the given time.

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/keys
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/keys')

Response

Status: 200 OK
[
  {
    "key": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234",
    "id": 2,
    "url": "https://api.github.com/user/keys/2",
    "title": "ssh-rsa AAAAB3NzaC1yc2EAAA",
    "created_at": "2020-06-11T21:31:57Z",
    "verified": false,
    "read_only": false,
    "last_used": "2020-06-11T22:31:57Z",
    "user_id": 1,
    "repository_id": 2
  },
  {
    "key": "9Og8iYjAyymI9LvABpJerYrMxURPc8r+dB7TJyvv1234",
    "id": 3,
    "url": "https://api.github.com/user/keys/2",
    "title": "ssh-rsa AAAAB3NzaC1yc2EAAA",
    "created_at": "2020-06-11T21:31:57Z",
    "verified": false,
    "read_only": false,
    "last_used": "2020-06-11T22:31:57Z",
    "user_id": 1,
    "repository_id": 2
  }
]

delete /admin/keys/{key_ids}

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

key_ids string path

Ejemplos de código

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/keys/KEY_IDS
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/keys/{key_ids}', {
  key_ids: 'key_ids'
})

Response

Status: 204 No Content

List personal access tokens

Lists personal access tokens for all users, including admin users.

get /admin/tokens

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

per_page integer query

Results per page (max 100)

Default: 30
page integer query

Page number of the results to fetch.

Default: 1

Ejemplos de código

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/tokens
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/tokens')

Response

Status: 200 OK
[
  {
    "id": 2,
    "url": "https://enterprise.octocat.com/api/v3/authorizations/2",
    "app": {
      "name": "My personal access token",
      "url": "https://docs.github.com/enterprise/rest/reference/enterprise-admin#list-personal-access-tokens",
      "client_id": "00000000000000000000"
    },
    "token": "ghp_16C7e42F292c6912E7710c838347Ae178B4a",
    "hashed_token": "23cffb2fab1b0a62747863eba88cb9327e561f2f7a0c8661c0d9b83146cb8d45",
    "token_last_eight": "Ae178B4a",
    "note": "My personal access token",
    "note_url": null,
    "created_at": "2019-04-24T21:49:02Z",
    "updated_at": "2019-04-24T21:49:02Z",
    "scopes": [
      "admin:business",
      "admin:gpg_key",
      "admin:org",
      "admin:org_hook",
      "admin:pre_receive_hook",
      "admin:public_key",
      "admin:repo_hook",
      "delete_repo",
      "gist",
      "notifications",
      "repo",
      "user",
      "write:discussion"
    ],
    "fingerprint": null
  }
]

Delete a personal access token

Deletes a personal access token. Returns a 403 - Forbidden status when a personal access token is in use. For example, if you access this endpoint with the same personal access token that you are trying to delete, you will receive this error.

delete /admin/tokens/{token_id}

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

token_id integer path

Ejemplos de código

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/tokens/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/tokens/{token_id}', {
  token_id: 42
})

Response

Status: 204 No Content

Create a user

If an external authentication mechanism is used, the login name should match the login name in the external system. If you are using LDAP authentication, you should also update the LDAP mapping for the user.

The login name will be normalized to only contain alphanumeric characters or single hyphens. For example, if you send "octo_cat" as the login, a user named "octo-cat" will be created.

If the login name or email address is already associated with an account, the server will return a 422 response.

post /admin/users

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

login string body

Required. The user's username.

email string body

Required for built-in authentication. The user's email address. This parameter can be omitted when using CAS, LDAP, or SAML. For details on built-in and centrally-managed authentication, see the GitHub authentication guide.

Ejemplos de código

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/users \
  -d '{"login":"login"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/users', {
  login: 'login'
})

Response

Status: 201 Created
{
  "login": "octocat",
  "id": 1,
  "node_id": "MDQ6VXNlcjE=",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "gravatar_id": "",
  "url": "https://api.github.com/users/octocat",
  "html_url": "https://github.com/octocat",
  "followers_url": "https://api.github.com/users/octocat/followers",
  "following_url": "https://api.github.com/users/octocat/following{/other_user}",
  "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
  "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
  "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
  "organizations_url": "https://api.github.com/users/octocat/orgs",
  "repos_url": "https://api.github.com/users/octocat/repos",
  "events_url": "https://api.github.com/users/octocat/events{/privacy}",
  "received_events_url": "https://api.github.com/users/octocat/received_events",
  "type": "User",
  "site_admin": false
}

patch /admin/users/{username}

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path
login string body

Required. The user's new username.

Ejemplos de código

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/users/USERNAME \
  -d '{"login":"login"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/users/{username}', {
  username: 'username',
  login: 'login'
})

Response

Status: 202 Accepted
{
  "message": "Job queued to rename user. It may take a few minutes to complete.",
  "url": "https://api.github.com/user/1"
}

Delete a user

Deleting a user will delete all their repositories, gists, applications, and personal settings. Suspending a user is often a better option.

You can delete any user account except your own.

delete /admin/users/{username}

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path

Ejemplos de código

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/users/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/users/{username}', {
  username: 'username'
})

Response

Status: 204 No Content

post /admin/users/{username}/authorizations

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path
scopes array of strings body

A list of scopes.

Ejemplos de código

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/users/USERNAME/authorizations \
  -d '{"scopes":["scopes"]}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/users/{username}/authorizations', {
  username: 'username',
  scopes: [
    'scopes'
  ]
})

Response

Status: 201 Created
{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
  "token_last_eight": "Ae178B4a",
  "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
  "app": {
    "url": "http://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "fingerprint": "jklmnop12345678"
}

delete /admin/users/{username}/authorizations

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path

Ejemplos de código

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/admin/users/USERNAME/authorizations
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/users/{username}/authorizations', {
  username: 'username'
})

Response

Status: 204 No Content

Promote a user to be a site administrator

Note that you'll need to set Content-Length to zero when calling out to this endpoint. For more information, see "HTTP verbs."

put /users/{username}/site_admin

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path

Ejemplos de código

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/users/USERNAME/site_admin
JavaScript (@octokit/core.js)
await octokit.request('PUT /users/{username}/site_admin', {
  username: 'username'
})

Response

Status: 204 No Content

Demote a site administrator

You can demote any user account except your own.

delete /users/{username}/site_admin

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path

Ejemplos de código

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/users/USERNAME/site_admin
JavaScript (@octokit/core.js)
await octokit.request('DELETE /users/{username}/site_admin', {
  username: 'username'
})

Response

Status: 204 No Content

Suspend a user

If your GitHub instance uses LDAP Sync with Active Directory LDAP servers, Active Directory LDAP-authenticated users cannot be suspended through this API. If you attempt to suspend an Active Directory LDAP-authenticated user through this API, it will return a 403 response.

You can suspend any user account except your own.

Note that, if you choose not to pass any parameters, you'll need to set Content-Length to zero when calling out to this endpoint. For more information, see "HTTP verbs."

put /users/{username}/suspended

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path
reason string body

The reason the user is being suspended. This message will be logged in the audit log. If you don't provide a reason, it will default to "Suspended via API by SITE_ADMINISTRATOR", where SITE_ADMINISTRATOR is the person who performed the action.

Ejemplos de código

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/users/USERNAME/suspended \
  -d '{"reason":"reason"}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /users/{username}/suspended', {
  username: 'username',
  reason: 'reason'
})

Response

Status: 204 No Content

Unsuspend a user

If your GitHub instance uses LDAP Sync with Active Directory LDAP servers, this API is disabled and will return a 403 response. Active Directory LDAP-authenticated users cannot be unsuspended using the API.

delete /users/{username}/suspended

Parámetros

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path
reason string body

The reason the user is being unsuspended. This message will be logged in the audit log. If you don't provide a reason, it will default to "Unsuspended via API by SITE_ADMINISTRATOR", where SITE_ADMINISTRATOR is the person who performed the action.

Ejemplos de código

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  http(s)://{hostname}/api/v3/users/USERNAME/suspended \
  -d '{"reason":"reason"}'
JavaScript (@octokit/core.js)
await octokit.request('DELETE /users/{username}/suspended', {
  username: 'username',
  reason: 'reason'
})

Response

Status: 204 No Content