gitea.actions.variable

variable

The Actions variables of a repository, an organization or the authenticated account.

A variable is the readable counterpart of a secret: the same three scopes, the same paths with variables in place of secrets, and a value that comes back - under data - when it is read.

Where a secret has one endpoint that both creates and replaces, a variable has two, and they behave differently: create_variable answers 409 on a name that already exists, while update_variable replaces the value of one that does. So creating is safe to retry against a name believed to be free, and replacing is asked for rather than arrived at.

The listing here is the other bare-array listing of the Actions API: a list, not an object with total_count.

Classes

gitea.actions.variable.Variables

Variables(client: ClientProtocol)

Bases: BaseActions, Resource

The Actions endpoints over the variables of a scope.

Source code in src/gitea/resource/resource.py

def __init__(self, client: ClientProtocol) -> None:
    """Initialize the Resource with a Gitea client.

    Args:
        client: An instance of the Gitea client.

    """
    self.client = client

Methods:

gitea.actions.variable.Variables.list_variables

list_variables(
    owner: str | None = None,
    repository: str | None = None,
    page: int | None = None,
    limit: int | None = None,
    **kwargs: Any,
) -> tuple[list[dict[str, Any]], dict[str, Any]]

List the variables of a scope.

Parameters:

Name	Type	Description	Default
owner	str | None	The owner of the repository, or the organization whose variables are listed. Omitting both this and repository lists the variables of the authenticated account.	None
repository	str | None	The name of the repository, to list its variables alone.	None
page	int | None	The page number for pagination.	None
limit	int | None	The number of variables per page.	None
**kwargs	Any	Additional arguments for the request.	{}

Returns:

Type	Description
list[dict[str, Any]]	A tuple containing the variables as a list and a dictionary with
dict[str, Any]	metadata. Each entry carries the value under data, which is what
tuple[list[dict[str, Any]], dict[str, Any]]	makes a variable a variable rather than a secret.

Source code in src/gitea/actions/variable.py

def list_variables(
    self,
    owner: str | None = None,
    repository: str | None = None,
    page: int | None = None,
    limit: int | None = None,
    **kwargs: Any,
) -> tuple[list[dict[str, Any]], dict[str, Any]]:
    """List the variables of a scope.

    Args:
        owner: The owner of the repository, or the organization whose
            variables are listed. Omitting both this and `repository` lists
            the variables of the authenticated account.
        repository: The name of the repository, to list its variables alone.
        page: The page number for pagination.
        limit: The number of variables per page.
        **kwargs: Additional arguments for the request.

    Returns:
        A tuple containing the variables as a list and a dictionary with
        metadata. Each entry carries the value under `data`, which is what
        makes a variable a variable rather than a secret.

    """
    response = self._list_variables(owner=owner, repository=repository, page=page, limit=limit, **kwargs)
    data, status_code = process_response(response, default=[])
    return cast(list[dict[str, Any]], data), {"status_code": status_code}

gitea.actions.variable.Variables.get_variable

get_variable(
    variable_name: str,
    owner: str | None = None,
    repository: str | None = None,
    **kwargs: Any,
) -> tuple[dict[str, Any], dict[str, Any]]

Get one variable of a scope.

Parameters:

Name	Type	Description	Default
variable_name	str	The name of the variable.	required
owner	str | None	The owner of the repository, or the organization the variable belongs to. Omitting both this and repository reads a variable of the authenticated account.	None
repository	str | None	The name of the repository the variable belongs to.	None
**kwargs	Any	Additional arguments for the request.	{}

Returns:

Type	Description
dict[str, Any]	A tuple containing the variable as a dictionary, its value under
dict[str, Any]	data, and a dictionary with metadata.

Source code in src/gitea/actions/variable.py

def get_variable(
    self,
    variable_name: str,
    owner: str | None = None,
    repository: str | None = None,
    **kwargs: Any,
) -> tuple[dict[str, Any], dict[str, Any]]:
    """Get one variable of a scope.

    Args:
        variable_name: The name of the variable.
        owner: The owner of the repository, or the organization the variable
            belongs to. Omitting both this and `repository` reads a variable
            of the authenticated account.
        repository: The name of the repository the variable belongs to.
        **kwargs: Additional arguments for the request.

    Returns:
        A tuple containing the variable as a dictionary, its value under
        `data`, and a dictionary with metadata.

    """
    response = self._get_variable(variable_name=variable_name, owner=owner, repository=repository, **kwargs)
    data, status_code = process_response(response, default={})
    return cast(dict[str, Any], data), {"status_code": status_code}

gitea.actions.variable.Variables.create_variable

create_variable(
    variable_name: str,
    value: str,
    owner: str | None = None,
    repository: str | None = None,
    description: str | None = None,
    **kwargs: Any,
) -> tuple[dict[str, Any], dict[str, Any]]

Create a variable of a scope.

A name that already exists answers 409 rather than being replaced, so this never overwrites a value by accident; update_variable is how one is replaced on purpose.

Parameters:

Name	Type	Description	Default
variable_name	str	The name of the variable to create.	required
value	str	The value to store.	required
owner	str | None	The owner of the repository, or the organization the variable belongs to. Omitting both this and repository creates a variable of the authenticated account.	None
repository	str | None	The name of the repository the variable belongs to.	None
description	str | None	What the variable is for, shown alongside it in the web UI.	None
**kwargs	Any	Additional arguments for the request.	{}

Returns:

Type	Description
dict[str, Any]	A tuple containing an empty dictionary - the endpoint answers 201
dict[str, Any]	with no body - and a dictionary with metadata.

Source code in src/gitea/actions/variable.py

def create_variable(
    self,
    variable_name: str,
    value: str,
    owner: str | None = None,
    repository: str | None = None,
    description: str | None = None,
    **kwargs: Any,
) -> tuple[dict[str, Any], dict[str, Any]]:
    """Create a variable of a scope.

    A name that already exists answers `409` rather than being replaced, so
    this never overwrites a value by accident; `update_variable` is how one is
    replaced on purpose.

    Args:
        variable_name: The name of the variable to create.
        value: The value to store.
        owner: The owner of the repository, or the organization the variable
            belongs to. Omitting both this and `repository` creates a variable
            of the authenticated account.
        repository: The name of the repository the variable belongs to.
        description: What the variable is for, shown alongside it in the web
            UI.
        **kwargs: Additional arguments for the request.

    Returns:
        A tuple containing an empty dictionary - the endpoint answers `201`
        with no body - and a dictionary with metadata.

    """
    response = self._create_variable(
        variable_name=variable_name,
        value=value,
        owner=owner,
        repository=repository,
        description=description,
        **kwargs,
    )
    data, status_code = process_response(response, default={})
    return cast(dict[str, Any], data), {"status_code": status_code}

gitea.actions.variable.Variables.update_variable

update_variable(
    variable_name: str,
    value: str,
    owner: str | None = None,
    repository: str | None = None,
    new_name: str | None = None,
    description: str | None = None,
    **kwargs: Any,
) -> tuple[dict[str, Any], dict[str, Any]]

Update a variable of a scope, replacing its value and optionally its name.

Parameters:

Name	Type	Description	Default
variable_name	str	The name of the variable to update, which is how the endpoint is addressed.	required
value	str	The value to store. Gitea requires it, so an update meaning only to rename a variable still sends the value it is to keep - read it with get_variable first rather than guessing.	required
owner	str | None	The owner of the repository, or the organization the variable belongs to. Omitting both this and repository updates a variable of the authenticated account.	None
repository	str | None	The name of the repository the variable belongs to.	None
new_name	str | None	A name to rename the variable to, sent as the API's name. Omitting it leaves the name alone.	None
description	str | None	What the variable is for.	None
**kwargs	Any	Additional arguments for the request.	{}

Returns:

Type	Description
dict[str, Any]	A tuple containing an empty dictionary - the endpoint answers without
dict[str, Any]	a body - and a dictionary with metadata.

Source code in src/gitea/actions/variable.py

def update_variable(
    self,
    variable_name: str,
    value: str,
    owner: str | None = None,
    repository: str | None = None,
    new_name: str | None = None,
    description: str | None = None,
    **kwargs: Any,
) -> tuple[dict[str, Any], dict[str, Any]]:
    """Update a variable of a scope, replacing its value and optionally its name.

    Args:
        variable_name: The name of the variable to update, which is how the
            endpoint is addressed.
        value: The value to store. Gitea requires it, so an update meaning
            only to rename a variable still sends the value it is to keep -
            read it with `get_variable` first rather than guessing.
        owner: The owner of the repository, or the organization the variable
            belongs to. Omitting both this and `repository` updates a variable
            of the authenticated account.
        repository: The name of the repository the variable belongs to.
        new_name: A name to rename the variable to, sent as the API's `name`.
            Omitting it leaves the name alone.
        description: What the variable is for.
        **kwargs: Additional arguments for the request.

    Returns:
        A tuple containing an empty dictionary - the endpoint answers without
        a body - and a dictionary with metadata.

    """
    response = self._update_variable(
        variable_name=variable_name,
        value=value,
        owner=owner,
        repository=repository,
        new_name=new_name,
        description=description,
        **kwargs,
    )
    data, status_code = process_response(response, default={})
    return cast(dict[str, Any], data), {"status_code": status_code}

gitea.actions.variable.Variables.delete_variable

delete_variable(
    variable_name: str,
    owner: str | None = None,
    repository: str | None = None,
    **kwargs: Any,
) -> tuple[dict[str, Any], dict[str, Any]]

Delete a variable of a scope.

Parameters:

Name	Type	Description	Default
variable_name	str	The name of the variable.	required
owner	str | None	The owner of the repository, or the organization the variable belongs to. Omitting both this and repository deletes a variable of the authenticated account.	None
repository	str | None	The name of the repository the variable belongs to.	None
**kwargs	Any	Additional arguments for the request.	{}

Returns:

Type	Description
dict[str, Any]	A tuple containing an empty dictionary - the endpoint answers without
dict[str, Any]	a body - and a dictionary with metadata.

Source code in src/gitea/actions/variable.py

def delete_variable(
    self,
    variable_name: str,
    owner: str | None = None,
    repository: str | None = None,
    **kwargs: Any,
) -> tuple[dict[str, Any], dict[str, Any]]:
    """Delete a variable of a scope.

    Args:
        variable_name: The name of the variable.
        owner: The owner of the repository, or the organization the variable
            belongs to. Omitting both this and `repository` deletes a variable
            of the authenticated account.
        repository: The name of the repository the variable belongs to.
        **kwargs: Additional arguments for the request.

    Returns:
        A tuple containing an empty dictionary - the endpoint answers without
        a body - and a dictionary with metadata.

    """
    response = self._delete_variable(variable_name=variable_name, owner=owner, repository=repository, **kwargs)
    data, status_code = process_response(response, default={})
    return cast(dict[str, Any], data), {"status_code": status_code}

Functions: